SOURCE DEBUGGING AND PROCESS ENVIRONMENT 
COURSE CODE: F21 



STUDENT HANDBOOK 



FSO ISSUE date: JULY 1981 



HONEYWELL INFORMATION SYSTEMS 
"' MARKETING EDUCATION 



Copyright (c) 

Honeywell Information Systems, Inc. 

The information contained herein is the exclusive property of Honeywell 
Information Systems, inc., axcept as otherwise indicated, and shall not 
be disclosed or reproduced, in whole or in part, without explicit written 
authorization from the company. The distribution of this material outside 
the company may occur only as authorized. 

Printed in the United States of America 

ATI rinhn ra<»rv*<l 



CONTENTS 



Page 

Topic I Debugging Programs on Multics 1-1 

Types of Programming Errors 1-1 

List of Debugging Tools 1-5 

Other Programming and Debugging Tools .... 1-6 

Source-Level Debugging 1-8 

Object Level Debugging. ... . 1-10 

Topic 11 SOURCE LEVEL DEBUGGING - AN INTRODUCTION TO THE 

probe COMMAND 2-1 

The probe Environment 2-1 

A Sample Program 2-4 

SCENARIO ONE: FUNDAMENTAL probe . 2-11 

Scenario Two: More probe 2-17 

Breaking Program Execution. ... 2-25 

Scenario three: Simple Break Processing . . . 2-29 

additional Break Control . 2-35 

Probe Odds and Ends 2-54 

Topic III Other Source-Level Debugging Commands ,,,... 3-1 

The trace Command 3-1 

Interaction of the Control Arguments 3-5 

■ Tracing Example One 3-6 

Other trace Control Requests 3-11 

Trace Example Two. 3-14 

The display pllio error Command ........ 3-20 

A display pllio error Example 3-21 

Topic IV Advanced probe Requests 4-1 

Introduction 4-1 

Scenario I - More probe .Control 4-2 

Control of Output Processing 4-7 

Scenario III - Program Manipualtion 4-9 

Scenario IV - probe Variables 4-14 

Topic V MULTICS USER RING RUNTIME STRUCTURES 5-1 

Introduction 5-1 

Supervisor Segments . 5-3 

The Stack Segment - stack_n 5-6 

The area. linker Segment 5-11 

Getting Space for Program Variables . 5-23 

Topic VI MULTICS DYNAMIC LINKING 6-1 

Introduction 6-1 



ii F21 



CONTENTS (con't) 



Page 

Multics Compiler Conventions 6-8 

Mutlics Operating Svstem Support 6-11 

The Linker - Phase I. . . .* 6-13 

The Linker - Phase II ..... 6-19 

By-Products of Dynamic Linking. ....... 6-36 

Topic VII The Multics Programming Environment ....... 7-1 

Destruction of the Programming Environment. . 7-1 
Error Recovery Techniques 7-8 

Topic VIII Other Useful Debugging Tools. .......... 8-1 

1 ist_external_var iables ... 8—1 

list_external_variables . 8-1 

reset_external_variables 8-2 

reset_external_variables 8-2 

delete_external_variables 8-3 

delete_external_variables 8-3 

print_bind_map. . . 8-4 

print_bind__map 8-4 

print link inj.o ............... 8 — 5 

print_link_inf o , pi i 8-5 

resolve_linkage_error 3-7 

reslve_linkage_error , rle . 3-7 

trace_stack 3-8 

trace_stack, ts 5-8 

Appendix A Debugging Tools A-l 

area_status A-l 

area_status A-l 

cancel_cobol_program A-2 

cancel_cobol_program, ccp A-2- 

create_area A-4 

create_area A-4 

create__data_segment A-5 

create_data_segment , cds. A-5 

cumulative_page_trace A-6 

cumulative_page_trace,cpt A-6 

cv_ptr_ A-9 

cv_ptr_ A-9 

delete_external_variables A-l 2 

delete_external_var iables , . A-12 

display_cobol_run_unit A-l 3 

display_cobol_run_unit, dcr A-l 3 

display_pllio__err A-l 4 

display_pllio_err , dpe A-14 

dump_segment. A-l 5 

dump_segment, ds A-l 5 

io_call A-18 

iU Wul 1 ^ I U s j, « « * t 6 * « c • * • * e a * rt~" _L O 

lilt external variables A-31 



iv F21 



CONTENTS (con't) 



Page 



list_external_variables . A-31 

list_temp_segir.ents. A-32 

list__temp_segments A-32 

pay 6 CTaCB ■••«•«•••«*• •-***'*a* £h™ j ^s 

page__trace, pg t ......... . A-34 

pr int_j3ind_map. . A-36 

print_bind_map. ................ A-36 

pr int_link__info ............... A-37 

print_link_info, pli. ............ . A-37 

print__linkage_usage A-39 

pr int_linkage_usage, plu. . , A-39 

probe A-40 

probe, pb A-40 

profile A-76 

profile A-76 

reset_external_variables A-79 

reset_external_variables A-79 

resolve_linkage_error A-80 

reslve_linkage_error , rle A-80 

run__cobol .................. A-81 

run_cobol, re ..... A-81 

set_fortran__common A-84 

set_fortran_coramon, sfc A-84 

set_systera_storage A-86 

set_systera_storage. ..." A-86 

set_user_storage . ,,....,.....*. A-88 

set_user_storage A-88 

stop_cobol_run A-90 

stop_cobol_run, scr A-90 

trace A-91 

trace A-91 

trace_stack A-102 

trace_stack, ts A-102 

Appendix W Workshops W-l 

Workshop One W-l 

Workshop Two W-10 

Workshop Three W-l 3 



F21 



TOPIC I 



Debugging Programs on Multics 1-1 

Types of Programming Errors ......... l-l 

List of Debugging Tools 1-5 

Other Programming and Debugging Tools .... 1-6 

Source-Level Debugging. ...... 1-8 

Object Level Debugging 1-10 



1-i 



Topic I DEBUGGING PROGRAMS ON MULTICS Topic I 

OBJECTIVES: 

Upon completion of this topic* students should be able tos 

1. Describe the methods used to find and correct syntactical 
errors. 



iA t« f i r\A ind rnrrart e atttia lit. i r 



errors . 



3. List some of the more common source-level defaussins tools. 



4. Outline* in general termsr the concepts of source-level 
debugging as opposed to object-level debussina. 
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TYPES OF PROGRAMMING ERRORS 

a TWO KINDS OF ERRORS (BUGS) COMMONLY OCCUR IN PROGRAMS 

I SYNTAX ERRORS 

I TYPING ERRORS 

I MISUSE OF A LANGUAGE STATEMENT 

• I SEMANTIC ERRORS 

I SPECIFYING THE 'WRONG DATA 

I USING DATA INCORRECTLY 

I ATTEMPTING TO REFERENCE MORE DATA THAN IS PRESENT 

I PERFORMING INVALID OPERATIONS ON THE DATA 

T BfoifnDMTMr: a.M T-wppiDoirr'T 1 apninTMrf np nopoiTTriMS nw thp naTa 
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TYPES OF PROGRAMMING ERRORS 



a SYNTAX ERRORS 

I CAN BE DETECTED BY 

I PROOFREADING THE PROGRAM 



I COMPILING THE PROGRAM AND OBSERVING THE ERROR DIAGNOSTIC 
MESSAGES 



I CAN BE CORRECTED BY 



I EDITING THE SOURCE PROGRAM TO CORRECT THE ERRORS (DIAGNOSED 
BY THE COMPILER OR FOUND DURING PROOFREADING) 



I RECOMPILING THE SOURCE 

I REPEATING THIS PROCESS UNTIL NO MORE ERRORS ARE DIAGNOSED 
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TYPES OF PROGRAMMING ERRORS 



a SEMANTIC ERRORS 



CAN BE DETECTED BY 



I PROOFREADING THE PROGRAM 



I INSERTING TEMPORARY STATEMENTS IN THE PROGRAM SOURCE TO PRINT 
INFORMATION ABOUT DATA VALUES, FLOW OF CONTROL, ETC. 

I ARE INTERMEDIATE DATA VALUES CORRECT? 

I DOES THE POINT OF EXECUTION FLOW THROUGH THE PROGRAM IN 
THE EXPECTED WAY? 



I RUNNING THE PROGRAM AND OBSERVING 

I WHETHER OR NOT THE PROGRAM RUNS TO COMPLETION 

I DOES THE PROGRAM GO INTO A LOOP? 

I DOES AN UNEXPECTED ERROR CONDITION OCCUR WHICH HALTS 
P R QGR AM EXECUTION? 

I WHETHER OR NOT THE PROGRAM PRODUCES THE EXPECTED RESULTS 

I DOES THE PROGRAM PRODUCE CORRECT OUTPUT DATA? 

I DOES THE PROGRAM DIAGNOSE INCORRECT INPUT DATA? 

I CAN BE CORRECTED BY 

I IDENTIFYING THE POINT OF ERROR 

I EDITING THE SOURCE PROGRAM TO CORRECT THE ERRORS 

I RECOMPILING THE SOURCE 
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TYPES OF PROGRAMMING ERRORS 



I REPEATING THIS PROCESS UNTIL THE PROGRAM OPERATES CORRECTLY 
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LIST OF DEBUGGING TOOLS 



a MAJOR TOOLS FOR DIAGNOSING 

I SYNTAX ERRORS 

I THE COMPILERS 

I PH 
I cobol 

I fortran 



I SEMANTIC ERRORS 

I SOURCE-LEVEL DEBUGGING TOOLS 
I probe 
I trace fec^Ji^-e c «." s 

I OBJECT-LEVEL DEBUGGING TOOLS 
debug 

trace_stack 
dump_segment 
pr int_l ink info 
print_bind_map 
display_component_name 
pr int_l inkage_usage 
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OTHER PROGRAMMING AND DEBUGGING TOOLS 

I FILE MANIPULATION TOOLS 

I io^call 

I print__attach_table 

I close_file 

I vfile_status 

I vfile_adjust 

I adjust_bit_count 

1 set_bit_count 

I EXTERNAL REFERENCE MANIPULATION TOOLS 

I resolve_linkage_error 

I Iist__external_var iables 

I delete_external_variables 

I reset_external_var iables 

I set_fortran_common 

I create_data_segment 

I error_tabie__compiler 

I COBOL RUN UNIT TOOLS 
I run_cobol 

I display_cobol__run_unit 
I stop_cobol_run 
I cancel cobol program 
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OTHER PROGRAMMING AND DEBUGGING TOOLS 

I GENERAL RUN UNIT COMMANDS 
I run 
I stop_run 

I SEARCH RULE AND DYNAMIC LINKING TOOLS 
I pr int_search_ruies 
I add_search_rules 

I delete search rules 

l -' ~ "" 

I where 

I list_re£_names 

I initiate 

I terminate 

I terminate_ref name 

T f a yini n a f a o i ^n 1 c ^aPw am to. 

I terminate_segno i«> & « t^iUzt of l«>«-»?v*- 

I AREA MANIPULATION TOOLS 
I area__status 
I create_area 
I set_user_storage 
I set_system_storage 
I list_temp_segments 
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SOURCE-LEVEL DEBUGGING 

a SOURCE-LEVEL DEBUGGING ALLOWS THE PROGRAMMER TO 

I DISPLAY PROGRAM SOURCE STATEMENTS 
I GIVEN A STATEMENT LABEL 
I GIVEN A LINE NUMBER 

I DISPLAY THE VALUE OF PROGRAM DATA VARIABLES 
I GIVEN THE NAME OF THE VARIABLE 

I DISPLAY THE VALUE OF PROGRAM DATA VARIABLES 

I GIVEN THE STORAGE LOCATION AND DATA FORMAT OF THE VARIABLE 

I DISPLAY THE DECLARATION OF A PROGRAM VARIABLE 

I DISPLAY THE LIST OF (USER RING) ACTIVE PROGRAMS 
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SOURCS-LSVSL DEBUGGING 

SOURCE-LEVEL DEBUGGING ALLOWS THE PROGRAMMER TO 

I SET BREAKPOINTS BEFORE OR AFTER STATEMENTS 

I TO INTERRUPT NORMAL FLOW OF EXECUTION 

I TO INTERROGATE THE STATE OF THE EXECUTING PROGRAM 

1 TO CHANGE THE VALUE OF PROGRAM DATA 

I TO ALTER THE FLOW OF EXECUTION THROUGH THE PROGRAM 

I TO CONDITIONALLY PERFORM ANY OF THESE FUNCTIONS 

I ONLY IF A PROGRAM DATA VALUE MEETS SOME CONDITION 

I REPEATEDLY WHILE A PROGRAM DATA VALUE MEETS SOME CONDITION 

I TRACE CALLS TO A PARTICULAR PROGRAM 

I CALL PROGRAMS WHICH EXPECT NON-CHARACTER ARGUMENTS 
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OBJECT LEVEL DEBUGGING 

a OBJECT-LEVEL DEBUGGING TOOLS ALLOW THE PROGRAMMER TO 

I PERFORM MOST SOURCE-LEVEL DEBUGGING FUNCTIONS, PLUS 

I CHANGE THE VALUE OF PROGRAM DATA VARIABLES 

I GIVEN THE STORAGE LOCATION AND DATA FORMAT OF THE VARIABLE 

I DISPLAY PROGRAM SOURCE STATEMENTS 

I GIVEN A LOCATION IN THE PROGRAM OBJECT SEGMENT 



r DISPLAY AND CHANGE THE VALUE OF MACHINE INSTRUCTIONS COMPILED TO 
EXECUTE A SOURCE STATEMENT 



I DISPLAY THE FORMATTED CONTENTS OF 

I THE PROGRAM ACTIVATION HISTORY SEGMENT (THE STACK) 
I AREA SEGMENTS 
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OBJECT LEVEL DEBUGGING 

a OBJECT-LEVEL DEBUGGING TOOLS ALLOW THE PROGRAMMER TO 

I DISPLAY AND CHANGE THE CONTENTS OF ANY SEGMENT 
I GIVEN ITS PATHNAME 
I GIVEN ITS REFERENCE NAME 
I GIVEN ITS SEGMENT NUMBER 



I WHEN THE USER HAS ADEQUATE ACCESS TO PERFORM THE REQUESTED 
OPERATION 



I DISPLAY AND CHANGE THE CONTENTS OF HARDWARE REGISTER IMAGES 
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Topic II SOURCE-LEVEL DEBUGGING <PROBE) Topic II 

OBJECTIVES: 

Upon completion of this topic? students should be able to: 



1. Use the appropriate PL/1 compiler control arsuments to enable 
probe to function on an object segment. 



2. Describe the different situations under which probe may be 
invoked. 



3. Debus a program using the following probe requests: 

source (sc) 
value <v) 
symbol <sb> 
quit < <i > 
help 
stack (sk) 

4. Manipulate breakpoints in a program usins the following probe 
requests: 

position <ps)r status <st) 

be fore (b)» after < a ) » reset <r) 

continue (c)» continue-to (ct)» step (s) 

5. Use the probe builtin functions. 
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THE PROBE ENVIRONMEN r 



£9 CiiN v xnuiNrlEiiN a uv&rwxaw 

I FUNCTIONS AS A SUBSYSTEM FOR PROGRAM RECOVERY 

I DRIVEN BY INTERACTIVE REQUESTS 

I LONG AND SHORT FORMS AVAILABLE 

I REQUEST DELIMITER IS EITHER NEW LINE OR SEMI-COLON 

I WORKS BEST WITH COMPILER GENERATED SYMBOL TA3LE 

I CURRENTLY AVAILABLE FOR COBOL, FORTRAN, AND PL/I 

I USE -table OPTION f\^*~ 

I MAY ALSO USE -short table OPTION 



r 07:47 0.159 43 

pll check_back_ issues -sv2 

PL/I 26a 

r 07:48 3.391 221 

probe check_back__issues 

probe: Cannot get statement map for this procedure. 

r 07:48 0.108 31 

pll check_back_issues -sv2 -tb 

PL/I 26a 

r 07:48 3.486 217 

probe check_back_issues 

Using check_back_issues (no active frame) . -c>o^ o^ _^> \fvo«- 

source 

check back issues: 

proc; 
quit 
r 07:49 0.173 21 
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THS PR03B ENVIRONMENT 

I MAY BE INVOKED FROM SEVERAL SITUATIONS 

I AFTER AN UNHANDLED CONDITION (READY LEVEL NOT EQUAL TO ONE) 

I AT READY LEVEL ONE WITH NO PROGRAM SPECIFIED ]o <? K^^-s JT*<-K 

I AT READY LEVEL ONE WITH PROGRAM SPECIFIED 

p 

I IMPLICITLY AT A PREVIOUSLY SET 3REAKP0INT 

I MANAGES TWO IMPORTANT PIECES OF INFORMATION 

I SOURCE POINTER 

I FRAME OF PROGRAM (ONLY IF ACTIVE) 
I BLOCK OF CODE WITHIN PROGRAM- 
I LINE OF CODE WITHIN PROGRAM 
I BASED UPON MANNER OF INVOCATION 

I CONTROL POINTER 

I LAST INSTRUCTION EXECUTED 

I BASED UPON MANNER OF INVOCATION 

I USUALLY AT BREAKPOINT, FAULTING INSTRUCTION, OR FIRST 
INSTRUCTION IN 3L0CK 



a USES A PERMANENT DATA BASE FOR OPERATION 



Not To Be Reproduced 2-2 F21 



THE PROBE ENVIRONMENT 

I LOCATED AT >udd>[user pro ject] > [user name] > [user name] .probe 

I CONTAINS PATH NAMES OF PROGRAMS WITH BREAKPOINTS SET IN THEM 

I IS REFERENCED BY probe WHENEVER 

I A BREAKPOINT IS ESTABLISHED OR FREED 

I A BREAKPOINT IS ENCOUNTERED WHILE A PROGRAM IS RUNNING 



I IF THIS DATA BASE IS DELETED, probe LOOSES INFORMATION ABOUT 
BREAKPOINTS 

I IF probe COMPLAINS ABOUT A "seg_fault" THE DATA 3ASE MAY BE 
DELETED 

I probe CANNOT FREE ANY BREAKPOINTS THAT HAVE BEEN PREVIOUSLY 
SET 

I TO FREE ANY "LOST" BREAKPOINTS, ONE MUST RECOMPILE THE 
AFFECTED PROGRAM 
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A SAMPLE PROGRAM 



THE EXAMPLE FOR THIS COURSE 



I IS WRITTEN IN PL/I 



I IS FAIRLY WELL STRUCTURED 



I IS EASY TO READ IF YOU ALREADY KNOW A FORTRAN OR COBOL RELATED 
LANGUAGE 



I HAS SOME BUGS IN IT 



I WILL 3E USED IN THE DEBUGGING SCENARIOS THAT FOLLOW 
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A SAMPLE PROGRAM 



a THE FOLLOWING PROGRAM IS SUPPOSED TO 



I KEEP TRACK OF BACK ISSUES OF MAGAZINES OF A SMALL COMPANY 

I EACH RECORD CONTAINS THE NUMBER OF ISSUES LEFT IN STOCK, HOW 
MANY ARE REQUESTED FOR SHIPPING, AND THE CURRENT COST OF 
PURCHASE 



I PRINT OUT A SUMMARY OF THIS DATA 

I ACCEPT TWO INPUT STRINGS 

I BOTH IN THE FORM OF volume: number 

I SPECIFY THE FIRST AND LAST ISSUES TO BE SUMMARIZED 

I PRINT OUT EACH RECORD AND CALCULATE RUNNING TOTALS 
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A SAMPLE PROGRAM 



B THE PROGRAM 



check_back_issues: 
proc; 

/is********************************* ******** 

* declarations for check_back_issues * 

* and its subroutines' * 

del back_issues file; 

del (f irst_issue, last^issue) char (12); 

del (fiirst__issuej3eiim, last_issue_del ira) fixed bin (24); 

del index builtin; 

del substr builtin; 

del number_of_issues fixed bin; 

del issue fixed bin; 

del 1 issue_record , 

2 current_inventory fixed bin (17) , 

2 pending_requests fixed bin (17), 

2 cost_of_issue fixed dec (8,2); 
del to tal_number pending fixed bin; 
del total_number_stocked fixed bin; 
del total_stock_value fixed dec (8,2); 
uOi iCurtSuL voxuine, current nuntuer; t i x eu uin; 
del ( last_issue_num, f irst_ii"sue_num) fixed bin; 
del (sysin, sysprint) file; 

del ( f irst_issue_volume, last issue volume) fixed bin; 
del colon internal static options (constant) 

char (1) aligned init (":"); 

open file (back_issues) keyed sequential input; 

* get number of the first and last issues * 

* the user wants to check. the form is * 

* volumemumber . this routine will split * 

* the components up into issue volume * 

* and issue_number , and position to that * 

* record in the file. * 

put list ("from (specify vol:num): "); 

get list ( f irst_issue) ; 

put list ("to (specify vol:num): "); 

get list (last issue); 
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A SAMPLE PROGRAM 



first issue delira = index (£irst_issue , colon); 
last_Tssue_c[elim = index (last_issue, colon); 
f irst__issue_volume = 

substr (£irst_issue, 1, f lrst__issue_delim) ; 
Xast_issue_volume = 

substr (last_issue, 1, last_issue_delim) ; 
f irst_issue_num = 

substr (f irst_issue, f irst_issue__delim) ; 
Xast_issue_num = 

""substr (last_issue, last_issue_del im) ; 

call position_f ile ( f irst_issue_volume, 
£irst_issue_num) ; ~* 

number of_issues = 

(F*last issue_volume + last_issue_num) - 
(6*f irst__issue__yolume + £irst_issue__num) ; 

do issue = 1 to number_o£_ issues; 

call print_record {); 
end; 

call print_summary (); 

close file (back_issues) ; 

return; 

* begin support subroutines * 
a*********************-***********/ 

print__record : 

proc (); 

* this subroutine obtains the next record * 

* from the back_issues file, calculates * 

* some totals, and outputs the currant * 

* record in a formatted form. * 
**********************************************/ 

call get_record () ; 

total_number_pending = 

total^jiumber^pending + 

issue recordTpending_requests; 
total_number_stocked = 

total_number_stocked + 

issue_record.current_inventory; 
total stock_value = 
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A SAMPLE PROGRAM 



totalis to ck_value + 

( issue_record. cur rent inventory* 

issue^record.cost of issue) ; 

put skip edit {"volume", 
current volume, 
"number 11 ", 
curr ent_number , 
"stocked:" , 

issue_record.current_inventory , 
"outstanding requests:", 
issue_record.pending_requests, 
"cost of this issue:", 

issue record. cost of issue, 
-.«) - ~ ~ 

(r (output format_l) } 
file (sysprint) ; 

return; 

output_format 1 : 

format (a{6), x(l), £(3,0), x(l), 

a(6), x(l), f{3,0), skip (1), x(ll), 

a(8) , x(l) , f (6,0) , x(l) , 

a(21) , x(l) , f (6,0) , x(l) , 

a(19), x(l), p"$$$,$S3v.39", a(l)) ; 

end print record; 



posit ion_f ile: 

proc (first_vol, first_num); 



* 
* 

* 



this subroutine positions the back issues * 

file to the record specified by the * 

first issue specifier given by the user * 

* at the beginning of the program, to * 

* position to the record, we simply read * 

* records we don't want and do nothing with * 

* them. * 

del (first_vol, first_num) fixed bin; 

do while (first_vol > current_volume) ; 

call get_record {); 
end; 

do while (first_num > current_number) ; 

call get__record (); 
end; 
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A SAMPLE PROGRAM 



r e t u r n ; 
end posi tion_f ile; 
get_record: proc (); 

del key char (8 ) ; 

/*********************************************** 

* this subroutine reads a record from the * 

* back issue file into the issue record. * 

* the other necessary information, vol * 

* and num of the issue, was stored in * 

* the record's key. we must extract this * 

* from our internally declared key and * 

* place it in the globally available * 

* current volume and current_number vars * 

read file (back_issues) 
into ( issue_record) 
keyto (key) ; 

current_volume = substr (key, 1, 4); 
current_number = substr (key, 5, 4); 

return; 
end get record; 



pr int_summary : 

proc (); 

* a simple subroutine, all this * 

* does is print out the totals * 

* calculated by the print_record * 

* subroutine. * 

put skip (2) 

edit ("number of issues stocked:", 

total_jiumber_stocked , 

"number of requests pending:", 

total_number_pend ing , 

"total stock value:", 

total stock value, 

".") " 

(r (output_format_2) ) 

file (sysprint) ; 
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A SAMPLE PROGRAM 



output_format_2 : 

format (a(25), x(l), f(6,0), skip (1), 
a(27) , x(l) , f (6,0) , skip (1) , 
a(18), x(l), p ,, $$$,$$9v.99 n , a(l)) ; 

end print_summary; 

end check back issues; 
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SCENARIO ONE: FUNDAMENTAL PROBE 



a SOME PRIMARY probe REQUESTS 

I THE source REQUEST 

I PRINTS SOURCE STATEMENTS 

I USAGE: 
source 
sc 

source <number of lines> 
sc <number of lines> 

■ I EXAMPLES: 
source 7 

SC 3 



I THE value REQUEST 

I DISPLAYS THE VALUE OF A SINGLE VARIABLE, AN EXPRESSION, OR 
SECTION OF AN' ARRAY 



I USAGE: 

value <expression> 

v <expression> 

value <array cross section> 

v <array cross section> 
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SCENARIO ONE: FUNDAMENTAL PROBE 

* 

I EXAMPLES : 
value x 

value array (1:5) 
value strl.raem2.elem 
v ptrl -> some_based var 
v ptr2 -> really_big.meml.comp (2). 2 

I SPECIFYING THE EXPRESSION FOR THE value REQUEST 

I MADE FROM PROGRAM VARIABLES, CONSTANT VALUES AND probe 
DEFINED FUNCTIONS 

I PROGRAM VARIABLES MUST APPEAR EXACTLY AS THEY WERE TYPED 
IN YOUR PROGRAM 

loop_counter (PL/I) 

VECT(l) (FORTRAN) 

data-part (COBOL) 

I CONSTANTS SHOULD BE IN A FORM ACCEPTABLE TO YOUR PROGRAM 

-99 

3.2e5 

"abode" 

'STRING' 

I probe MAINTAINS A SET OF BUILTIN FUNCTIONS THAT RETURN 
VALUES TO YOU 

addr - RETURNS THE ADDRESS OF ITS ARGUMENT 

add r el - RETURNS AN ADDRESS RELATIVE TO THE SPECIFICATION 
OF ITS ARGUMENTS 

baseptr - RETURNS THE ADDRESS OF THE BEGINNING OF A 
SEGMENT 

length - RETURNS THE LENGTH OF A 3IT OR CHARACTER STRING 
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SCENARIO ONE: FUNDAMENTAL PROBE 

maxlength - RETURNS THE MAXIMUM ALLOWED LENGTH OF A STRING 

null - RETURNS A SPECIAL INVALID ADDRESS 

octal - RETURNS THE MACHINE REPRESENTATION OF ITS ARGUMENT 

pointer - RETURNS AN ADDRESS BASED UPON ITS ARGUMENTS 

rel - RETURNS THE ADDRESS WITHIN A SEGMENT INTO WHICH ITS 
ARGUMENT POINTS 

segno - RETURNS THE NUMBER OF THE SEGMENT INTO WHICH ITS 
ARGUMENT POINTS 

substr - RETURNS A PORTION OF A CHARACTER OR BIT STRING 

unspec - RETURNS THE BINARY REPRESENTATION OF ITS ARGUMENT 

I AN EXPRESSION CAN CONTAIN OPERATORS 

I FOUR DEFINED WITHIN PROBE 

ADDITION - USE A PLUS SIGN (+} 

SUBTRACTION -USE A MINUS SIGN (-) 

MULTIPLICATION - USE AN ASTERISK (*) 

DIVISION - USE A SLASH (/) 

I ORDER IS MULTIPLICATION AND DIVISION, THEN ADDITION AND 
SUBTRACTION 

I ORDER MAY BE OVERRIDDEN WITH PARENTHESES 

I THE symbol REQUEST 

I SHOWS YOU THE DATA TYPE OF A PROGRAM VARIABLE 

I USAGE: 

symbol <name of variable> 
sb <name of variable> 
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SCENARIO QMS: FUNDAMENTAL PROBE 

I EXAMPLES: 
symbol x 
sb HYPTN 

I THE quit REQUEST 

I CAUSES YOU TO LEAVE PROBE 

I USED TO GET BACK TO COMMAND LEVEL 

I USAGE: 
quit 

q 



a THE SCENARIO 



I THE PROGRAM SLOWS UP 



I PROBE IS USED TO ASSESS THE DAMAGE 
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SCENARIO ONE: FUNDAMENTAL PROBE 



r 12:54 0.155 21 

check_back_issues 

from (specify vol:num):l:l 

to (specify vol:num):2:l 

Error: conversion condition by >udd>MEDmult>F21>doodle>bad_ 

\ccbi$check back_issuesl 540 (line 48) 

onsource = """1 : " , onchar = ":" 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 12:54 0.273 52 level 2 

probe 

Condition conversion raised at line 48 of check_back_issues 

\c ( level 7) . 

source 

f irst_issue_volume = 

substr (f irst_issue, 1, f irst_issue_delim) ; 

value f irst_issue_del im 
f irst__issue_delim =2 

value first_issue 
first_issue ="1:1 " 

value substr (f irst_issue, 1, f irst_issue_del im) ; 
" 1 : " 

symbol f irst_issue_volume 
fixed bin (17) automatic 
Declared in check_back_^issues 

v substr (first issue, 1, f irst_issue_del im - 1); 

q 

r 07:03 0.591 210 level 2 

rl 

r 07:03 0.045 9 
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SCENARIO ONE: FUNDAMENTAL PROBE 

I TECHNIQUE 

I INVOKE probe - IT TELLS YOU WHAT HAPPENED 

I FIND THE STATEMENT AT WHICH THE PROGRAM DIED 

I CHECK ALL THE VARIABLES IN THAT STATEMENT 
I NOTE THE IMPLICIT CONVERSION 
I THE SUBSTR BUILTIN WAS THE CULPRIT 



YOUR TURN 



I WHAT WAS THE PROGRAMMER TRYING TO DO WITH THE SUBSTRING BUILTIN? 



I HOW WOULD YOU CHANGE THE PROGRAM SO THAT THE IMPLICIT CONVERSION 

SUCCEEDS? . . 

I ARE THERE ANY OTHER STATEMENTS WHERE THIS CONDITION MAY HAPPEN? 
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SCENARIO TWO: MORE PROBE 



a AS ERRORS ARE FOUND THEY ARE FIXED 



I MODIFY THE SOURCE ONLY 



I RECOMPILE INTO NEW OBJECT 



I CLEAN UP ANY FILES THAT MAY HAVE BEEN LEFT INCONSISTENT 



qedx 

rcheck_back_issues.pll 

48 

first issue_volume = 
.+1 ■ 

substr (f irst__issue, 1, f irst_issue_del im) ; 

s/)/ - l)/p 

substr (f irst__issue, 1, f irst__issue_del im - l)j 

w 

q 

r 07:55 0.549 88 

pll check_back issues -tb -sv2 

PL/I 26a 

r 07:55 3.317 83 

r 07:55 0.049 8 

close file back issues 
r 07:38 0.082 23 



a RUN THE NEW PROGRAM 



I BE AWARE OF NEW PROBLEMS 
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I MAKE SURE THE OLD PROBLEM IS FIXED 



I LOOK FOR ANY EFFECTS YOUR CHANGE MAY HAVE ON OTHER PORTIONS OF 
THE PROGRAM 



check_back issues 

from (specify vol :nura) : 1: 1 

to {specify vol:num):l:4 

Error: conversion condition by >user_dir_dir>MEDrault>F21>do 

\ccdle>bad_cbi$check_back_issues] 551 (line 50) 

onsource = "1:", onchar = ":" 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 07:58 0.367 34 level 2 

probe 

Condition conversion raised at line 50 of check back issues 

\c (level 7) . 

source 

last__issue volume = ' 

substr (last_issue, 1, last_issue_del im) ; 
From Pandolf .MEDmult 05/19/81 0759.5 mst Tue : 
The handbooks came in today. I have them if you want to see 
\cthem. 

sm Pandolf .MEDmult good, be there later 
probe: Unknown request. " sm" 



a SOME INVALUABLE REQUESTS 

I THE list_requests REQUEST 

I LISTS ALL THE ALLOWED REQUESTS IN probe 

I USAGE: 
list_requests 
lr 
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list_requests 

Summary of probe requests; 



after, a 




args 

before, b 
call, cl 
continue, c 
continue_to, ct 




declare, del 

display, ds 
execute, e 




goto, g 
halt, h 
help 
if 




input switch, isw 
language, Ing 
let, 1 

list_help, Ih 
list builtins, lb 
list requests, Ir 
list variables, Isv 



Set a breakpoint after the specified statement. 

Print argument list for procedure. 

Set a breakpoint before the specified statement. 

Call a subroutine. 

Continue after a breakpoint. 

Resume execution from last breakpoint and stop 



at s n ecified statement. 



Create a probe variable. 

Display storage in various formats. 

Execute a Multics command line, usually 

within a break request. 
Continue execution at a specified statement. 
Halt ands re-enter probe. 
Print info files for probe requests. 
Execute probe requests based on specified 

condition. 
Set the I/O switch used for probe input. 
Display or set the current language. 
Change the value of a variable. 
List the available info topics for probe. 
Print a summary listing of all probe builtins. 
Print a summary listing of the probe requests. 
Print type and value of one or more probe 
™" variables, 

modes, mode Set probe operation modes. 
output_switch, osw Set the I/O switch used for probe output. 
pause, p Reset the current breakpoint and halt, 

position, ps Move the probe pointer to a new location 

and display the source, 
quit, q Leave probe and return to Multics command 

level. 
reset, r Reset breakpoints. 

source, sc Display source of program, 

stack, sk Display the stack. 

status, st Display the status of breakpoints, 

step, s Execute one statement and halt, 

symbol, sb Display information about the specified 

symbol . 
use Move the probe pointer to a new location, 

value, v Print the value of a variable or expression. 

where, wh Display the current values of the probe 

pointers, 
while, wl Execute probe requests while condition 

is true. 

Type "help" for more information. 
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SCENARIO TWO; MORS PROBE 

I THE help REQUEST 

I USAGE: 
help 

help <request> 
help <feature> 

I EXAMPLES: 
help 

help quit 
help EXPRESSIONS 

I THE execute REQUEST 

I ALLOWS A MULTICS COMMAND TO BE PROCESSED WHILE STILL IN probe 

I USAGE: 

execute <command line> 
e <command line> 

I EXAMPLES: 

execute "pwd" 
e "list *.pll" 
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SCENARIO TWO: MORE PROBE 



I USING THESE REQUESTS 



help execute 

09/27/79 The "execute" request. 

Syntax: execute STRING 

The contents of STRING are passed to the Multics command pro 

\ccessor . 

This request is chiefly useful in break request list, because 

\ce the more 

convenient escape to the Multics command processor is not av 

\cailable 

then. 

The user can pass an arbitrary line to the Multics command p 

\crocessor 

by preceeding it with ".." on a new line. 

Examples (5 lines) . More help?no 

execute sm Pandolf .MEDrault good, be there later 

probe (execute): The Multics command lines must be enclosed 

\cin quotes. 

e "sm Pandolf .MEDmult good, be there later" 
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I FINISHING UP THE CURRENT ERROR 



source 

last_issue_volume = 

substr (last_issue, 1, last__issue_deiim) ; 
value substr {last Issue, 1, last issue deTim) 
"1:" ~ - - 

sb last_issue_volume 

fixed "Bin (17) automatic 
Declared in check back_issues 
quit 
r 08:10 2.508 492 level 2 

qedx 

rcheck_back_issues.pll 
50,51p 

last_issue_volume = 
.+1 

substr (last_issue, 1, last_issue_del im) ; 
s/)/ - l)/p 

substr ( last__issue , 1, last_issue delim - 1); 
52,55p 

f irst_issue_num = 

substr (f irst_issue, f irst_issue_delim) ; 
last_issue_num = 

substr (last_issue, last_issue_del im) ; 
53s/)/ + l)/p 

substr (first issue, first issue delim + i); 
55s/)/ + l)/p 

substr (last_issue, last issue delim + 1); 
w 
q 
r 08:12 0.423 80 level 2 

pll check_back__issues -sv2 -tb 

PL/I 26a 

r 08:13 3.524 141 level 2 

rl 

r 08:15 0.046 29 

close file back_issues 
r 08:15 0.051 21 
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SCENARIO TWO: MORE PROBE 



a ADDITIONAL USE OF FUNDAMENTAL PROBE REQUESTS 



SOME USEFUL INFORMATION ABOUT A FAILURE WILL COME INDIRECTLY 
FROM THE probe DIALOGUE 



I NOTE THE USE OF value IN THE NEXT WINDOW 



check_back_ issues 

from (specify vol :num) : 1: 1 

to (specify vol :num) : 1 : 4 

Error: illegal__procedure condition by >user_dir_dir>MEDrault 
\c>F21>doodle>bad_cbi$print record|675 (line 98) 
(while in pil operator real~to_real_tr) 
referencing stack_4 16503 (in process dir) 

r 08:15 0.369 42 level 2 

pb 

Condition illegal_procedure raised at line 98 of print_recor 

\cd (level 8) . 

sc 

total_stock_value = 

"total_stock_value + 
( issue__record .current inventory* 
issue_record.cost_of_Tssue) ; 
,cost_of_issue 

.current 



inventory 



v issue record . 

co st_o"E_ issue 
v issue record. 

current_inventory = 22 
v to tal_stock_value 

total_stock_value = (invalid decimal data) 
symbol total stock_value 

fixed dec ("8", 2) automatic 
Declared in check back_issues 
value octal (total stock value) 
040 04004004004004004 0040040 
r 08:19 0.234 33 level 2 



rl 



r 08:19 0.037 2 



Not To Be Reproduced 



2-23 



F21 



SCENARIO TWO: MORE PROBE 



1 qedx 

1 rcheck_back__issues.pll 

1 /del total_stock value/ 

1 del total stock value fixed dec 

1 s/;/ init (0);/p 

j del total stock value fixed dec 

1 w 

I q 

1 . r 08:20 0.207 24 


(8,2); 1 
(8,2) init (0); 1 




1 oil check back issues -sv2 -tb 

1 PL/I 26a 

! r 08:21 3.461 233 




1 close file back issues 
I r 08:22 0.107 69 





I THE illegal_procedure CONDITION ITSELF EXPLAINED LITTLE ABOUT 
THE ERROR 



I THE PL/I STATEMENT WAS TOO COMPLEX TO QUICKLY DETERMINE THE 
IMMEDIATE CAUSE 



I THE value REQUEST UNCOVERED THE "FACT THAT ONE VARIABLE HAD 
INVALID DATA 



I BECAUSE OF THIS THE VALUE OF total_stock_value WAS 
UNPRINTABLE 



I THE octal BUILTIN FUNCTION ALLOWED US TO LOOK AT THE DATA 
THAT WAS THERE REGARDLESS OF THE DATA TYPE 



I THE PRESENCE OF SPACES (OCTAL 040) INDICATED THAT THE 
VARIABLE WAS NEVER INTIALIZED (TO OCTAL 06 0) 
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BREAKING PROGRAM EXECUTION 



a BREAKPOINTS 



I AT TIMES, THE PROGRAMMER DESIRES TO VIEW INTERMEDIATE PROGRAM 
VALUES 



I ONE OPTION IS TO PLACE I/O STATEMENTS IN THE SOURCE PROGRAM 
I COSTS TOO MUCH IN TERMS OF RECOMPILES 
I STILL PROVIDES NO WAY TO SUSPEND THE PROGRAM 

I LET THE DEBUGGER DO IT 

I RECOMPILING NOT NECESSARY TO CHANGE DEBUGGING BEHAVIOR 

I THE PROGRAM MAY BE SUSPENDED OR CONTINUE ON AFTER PRINTING 
OUT SOME DIAGNOSTIC 



a PROBE IMPLEMENTATION 



I REVOLVES AROUND THE "BREAKPOINT" 



I A LIST OF ONE OR MORE probe REQUESTS TO BE PERFORMED WHEN A 
STATEMENT IS REACHED 



I LIKE A SMALL PROGRAM FOR EACH STATEMENT 
I MODIFIABLE AT WILL BY THE PROGRAMMER 



I probe BREAKPOINTS CAN BE SPECIFIED TO BE EXECUTED EITHER BEFORE 
OR AFTER AN EXECUTABLE STATEMENT 
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BREAKING PROGRAM EXECUTION 



I BEFORES AND AFTERS ARE SEPARATE BREAKS, AND BOTH WILL BE 
EXECUTED IF ENCOUNTERED CONSECUTIVELY 



I COBOL COMPILER RESTRICTIONS LIMIT COBOL PROGRAMS TO THE USE 
OF BREAKPOINTS BEFORE THE STATEMENT ONLY 



a BREAKPOINT REQUESTS 

I THE before REQUEST 

I USAGE: 

before <line> 

b <line> 

before <line>: (<request list>) 

b <line>: (<request list >) 

I EXAMPLES: 
before 
before 50 



C before 5: (value x; value y) ^^> (v?^* K ' J?,\\)£ V' W>t\ ^V ^ 



before: value comp-val 



I NOTES: 



I. IF NO LINE NUMBER IS SPECIFIED, THE CURRENT LINE IS 
ASSUMED 

I IF ONLY ONE REQUEST IS DESIRED AT THE BREAK, THEN THE 
PARENTHESES MAY BE OMITTED 

I IF NO REQUEST IS SPECIFIED, THEN A "halt" REQUEST IS 
ASSUMED, CAUSING THE PROGRAM TO STOP AND PROBE TO 3E 
ENTERED 
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BREAKING PROGRAM EXECUTION 



I THE stack REQUEST 

I NOT SPECIFICALLY A BREAK REQUEST 

I DISPLAYS LIST OF ALL PROGRAMS THAT HAVE NOT FINISHED YET 

I ALLOWS YOU TO SEE HOW FAR YOUR PROGRAM HAS RUN 

I SHOWS RELATIONSHIPS BETWEEN PROGRAMS 

I MORE ON STACKS LATER 

I USAGE: 
stack 
sk 

stack <amount> 
sk <amount> 

stack <first frame, amount) 
sk <first frame, amount) 

I EXAMPLES: 
sk 

stack 4 
sk 12,3 

I THE position REQUEST 

I POSITIONS TO AND PRINTS A SPECIFIED SOURCE STATEMENT 
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BREAKING PROGRAM EXECUTION 



I USAGE: 

position <label> 
ps <+,-line> 
ps <line> 
ps <"string"> 

I EXAMPLES: 

position do label 
ps +3 
ps -4 
ps 63 
ps " i=5" 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 



a LET'S RETURN TO OUR EXAMPLE 






check_back_issues 

from (specify vol:num):l:l 

to (specify vol mum): 1:4 

volume 1 number 1 

stocked: 23 outstanding requests: cost 
\c of this issue: 

$5.00. 
volume 1 number 2 

stocked: 30 outstanding requests: 2 cost 
\c of this issue: 

$3.00. 
volume 1 number 3 

stocked: 27 outstanding requests: cost 
\c of this issue: 

$3.00. 
Error: size condition by >user_dir_dir>MSDmult>F21>doodle>b 
\cad cbi$print__summary 1 1255 (line i"93) 

PrecTsion of target insufficient for number of integral digi 
\cts assigned to it. 

system handler for error returns to command level 
r 08:23 0.420 40 level 2 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 



probe 

Condition size raised at line 193 of pr int_summary (level 8) 

source 

put skip (2) 

edit ("number of issues stocked:", 

to tal__numbe restocked , 

"number of requests pending:", 

total_number_pending , 

"totaT stock value:", 

total stock_value, 

(r (output__format_2) ) 

file (sysprint) ; 
stack 

15 simple_command_processor 1 12265 

14 command processor_! 11070 

13 abbrev_T533 6 

12 release_stack| 10031 

11 unclaimed_signali 27064 

10 wall|4436 

9 wall|4407 error 

8 print__summary (line 193) size 

7 check_back_issues (line 7 0) 

6 simple" command processor 1 12265 

5 command processor_| 11070 

4 abbrev T5336 

3 listen 1 10031 

c utojett state up 1^1/1/ 

1 user_init_admin 142452 (aim) 

sc 

put skip (2) 

edit ("number of issues stocked:", 

total_number__stocked , 

"number of requests pending:", 

total__number__pend ing , 

"totaT stock value:", 

total stock value, 

*'.")" 

(r (output_format_2) ) 

file (sysprint) ; 
v total_number_stocked 
total number_stocked = 4.30337e9 
position " total_number_stocked =" 
total_number_stocked = 

total number stocked + 

iss ue~~ r ec o rdTc ur r en t inventory; 
before 

Break set before line 95 
quit 
r 08:27 0.968 317 level 2 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 



I THE PROGRAM WILL NOW STOP BEFORE LINE 95 IS REACHED 

I probe IS AUTOMATICALLY INVOKED 

I THE REQUEST LIST IS PROCESSED 

I IN THIS CASE, WE ARE PLACED AT probe REQUEST LEVEL 

I IF THE halt REQUEST WAS NEITHER IMPLICITLY NOR EXPLICITLY 
STATED, EXECUTION WOULD CONTINUE WITH LINE 95 



rl 

r 08:27 0.041 10 

close_file back_issues 
r 08:28 0.049 17 

check_back_ issues 

from (specify vol :num) : 1: 1 

to (specify vol :num) ■; 1 : 4 
Stopped before line 95 of print record, (level 8) 
source 

total_number_stocked = 

total_number_stocked +■ 
issue_record.current_inventory; 
v total_number_stocked 
to tal__numbe restocked = 4.30337e9 
symbol total~number__stocked 

fixed bin (T7) automatic 
Declared in check_back_issues 

q 

r 08:30 0.441 115 



1 TECHNIQUE: 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 

I NOTE THE CONDITION: size 

I RESULT TOO BIG TO BE PLACED IN TARGET STORAGE LOCATION 
I DISAGREES WITH THE WAY THE PROGRAMMER THOUGHT TO USE II 

I FIND OUT WHERE THE VARIABLE IS ASSIGNED 
I SET BREAKPOINT THERE 
I LOOK AT VALUE OF VARIABLE AT THAT STATEMENT 

I THE VARIABLE HAD A RANDOM VALUE IN IT 

I IT WAS NOT INITIALLY SET 

I THIS CARRIED THROUGH UNTIL IT BLEW UP AT THE OUTPUT 
FORMATTING 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 



qedx 

rcheck back issues. pll 

/del total_number__stocked/ 

del total_number__stocked fixed bin; 

s/;/ init (0);/p 

del total_number stocked fixed bin init (0); 

w 

q 

r 08:30 0.256 30 

pll check_back_issues -sv2 -tb 

PL/I 26a 

r 08:31 3.549 111 

close file back issues 
r 08:31 0.057 8 

check_back__issues 

from (specify vol :num) : 1: 1 

to (specify vol:num):l:4 

volume 1 number 1 

stocked: 23 outstanding requests: cost of 
this issue: 

$5.00. volume 1 number 2 

stocked: 30 outstanding requests: 2 cost of 
this issue: 

$3.00. volume 1 number 3 

stocked: 27 outstanding requests: cost o£ 
this issue: 

$3.00. Error: size condition by 
>user_dir_dir>MEDmult>F21>doodle>bad_cbi$print_summary| 1304 
(line 193) Precision of target insufficient for number of 
integral digits assigned to it. system handler for error 
returns to command level 
r 08:32 0.467 22 level 2 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 



s YOUR TURN 



I THIS LOOKS LIKE THE SAME ERROR- IS IT? HOW DO YOU KNOW? 



I LIST THE STEPS YOU WOULD TAKE TO RESOLVE THIS ERROR, 
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Condition size raised at line 193 of print_summary (level 8) 
sc 

put skip (2) 

edit ("number of issues stocked:", 

total_number_stocked , 

"number of requests pending:", 

total_number_pend ing , 

"total stock value:", 

total stock value, 

".") " 

(r (output_format_2) ) 

file (syspr int) ; 
v to tal_number stocked 
total number stocked = 80 
v total_number_pend ing 
total_number pending = 4.30337e9 
v total_stoc"k"_value 
total_stock_value = 286 
sb total number_pend ing 

fixed bin (17} automatic 
Declared in check back_issues 

q 

r 08:33 0.386 79 level 2 

qx 

rcheck_back_issues.pll 
/del total_number_pending/ 

del total number_pend ing fixed bin; 

S/;/ init (0);/p 

del total_number_pend ing fixed bin init (0); 

w 

q 

r 08:34 0.216 35 level 2 

pll check_back_issues -tb -sv2 

PL/I 26a 

r 08:34 3.462 219 level 2 

rl 

r 08:34 0.040 6 

close__file back_issues 
r 08:35 0.042 7 
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ADDITIONAL BREAK CONTROL 

a MORE REQUESTS 

I THE after REQUEST 

I SETS UP A BREAKPOINT AFTER A GIVEN STATEMENT IN A PROGRAM 

I OPERATES EXACTLY LIKE THE before REQUEST 

I USAGE: 
after 
a 

after <line>: (<request list>) 
a <line>: (<request list>) 

I EXAMPLES: 
after 
after 100 
a 50: (value x; value y) 

I THE status REQUEST 

I LISTS BREAKPOINTS YOU HAVE SET IN YOUR PROGRAMS 
I USAGE: 
status 
st 

status <prograin name) 
st <program name> 
status <line in current program> 
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st <line in current program> 
status -all 
st -all 
status * 
st * 

I EXAMPLES: 
status 
status at 50 

status other-prog 
status -all 

I NOTES: 

"status -all" LISTS ALL BREAKS SET 

"status *" LISTS THE NAMES OF PROGRAMS WITH BREAKS SET 

AN OPTIONAL CONTROL ARGUMENT OF "-long" IS ALLOWED, WHICH 
PRINTS THE PROBE REQUEST LIST ASSOCIATED WITH THE BREAKPOINT 

I THE continue REQUEST 

I ALLOWS THE PROGRAMMER TO RESUME THE PROGRAM AFTER A BREAK 
THAT INVOKED probe 

I USAGE: 
continue 

c 

I EXAMPLES: 
continue 

c 
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ADDITIONAL BREAK CONTROL 



8 BACK TO THE SCENARIO 



I check back__issues 














I from (specify vol:n 


urn) : 1: 1 












I to {speci 


fy vol :num) : 1: 4 












i volume 1 number 


1 












I stocked: 23 


outstanding requests: 





cost 


of 


this 


issue : I 


1 $5.00. 














1 volume 1 number 


2 












1 stocked: 30 


outstanding requests: 


2 


cost 


of 


this 


issue : 1 


I $3.00. 














1 volume 1 number 


3 












1 stocked: 27 


outstanding requests: 





cost 


of 


this 


issue: 1 


1 $3.00. 














1 number of issues stocked: 80 












I number of requests 


pending: 2 












1 total stock value: 


$286.00. 












! r 08:36 0.264 7 















I A NEW PROBLEM: NOT ENOUGH RECORDS PRINTED OUT 



I WITH NO CONDITION SIGNALLED, BREAKPOINTS ARE THE ONLY WAY TO 
GET INTO PROBE WHILE THE PROGRAM IS RUNNING 



I WITHOUT SETTING TOO MANY BREAKS, ATTEMPT TO STOP THE PROGRAM 
AT APPROPRIATE PLACES AND LOOK AT LOOP VALUES 
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probe check_back_issues 

Using check_back__issues (no active frame) «, 

ps "do issue" 

do issue = 1 to number of issues; 
b 

Break set before line 66 
quit 
r 08:39 0.342 137 

check_back issues 

"From (specify vol:num):l:l 

to (specify vol :num) : 1: 4 

Stopped before line 66 of check back issues . (level 7) 

v number__of issues 
number_of_ issues = 3 

ps " number_of_issues =" 

number_of_issues = 

(6*last_issue_volume + last_issue_num) - 
(6*f irst_issue_volume + f irst_issue_num) ; 

v last_issue_volume 
last_issue_volume = 1 

v last_issue_num 
last_issue_num = 4 

v first issue_volume ; v f i rst_issue_num 
first__i¥sue volume = 1 
first""issue num = 1 



position +2 

call print_record () ; 

after 

Break set after line 67 

continue 
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volume 1 number 1 

stocked: 23 outstanding requests: cost of this issue; 
$5.00 .Stopped after line 67 of check_back_issues. (level 7) 
v i ss ue 
issue = 1 
c 

volume 1 number 2 

stocked: 30 outstanding requests: 2 cost of this issue; 
$3. 00. Stopped after line 67 of check_back_issues . (level 7) 
v issue 
issue = 2 
c 

volume 1 number 3 

stocked: 27 outstanding requests: cost of this issue: 
$3. 00. Stopped after line 67 of check_back_issues. (level 7) 
v issue 
issue = 3 
status 

Break exists after line 67 in check_back_issues 
3reak exists before line 56 in check_back_issues 
c 



number of issues stocked: 80 
number of requests pending: 2 
total stock value: $286.00.. 
r 08:46 1.185 380 



I TECHNIQUE: 

I IDENTIFY THE LOOP THAT PRINTS THE RECORDS 

I SET A BREAK WITHIN THE LOOP AND CHECK THE LOOP VARIABLE 



I LOCATE THE STATEMENT AT WHICH THE LOOP VARIABLE WAS 
INCORRECTLY SET . 



I FIX THE SOURCE 
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i qedx 

rcheck back issues .pll 

/number of_Tssues/ 

del numBer of Issues fixed bin; """ 

// " " 

number of issues - 

s/$/ 1 +/P 

number of_issues = 1 + 
w 

q 

r 09:09 0.270 80 

pll check_back__issues -sv2 -tb 

PL/I 26a 

r 09:10 3.668 234 

check_back issues 

from (specTfy volrnum): 1:1 

to (specify vol :nura) : 1 : 4 

'volume 1 number 1 

stocked: 23 outstanding requests: cost 
\cof this issue: 

$5.00. 
volume 1 number 2 

stocked: 30 outstanding requests: 2 cost 
\cof this issue: 

$3.00. 
volume 1 number 3 

stocked: 27 outstanding requests: cost 
\cof this issue: 

$3.00. 
volume 1 number 4 

stocked: 20 outstanding requests: 1 cost 
\cof this issue: 
$3.00. 

number of issues stocked: 100 
number of requests pending: 3 
total stock value: $346.00. 
r 09:10 0.362 28 
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I LOOKS GOOD; NOW TEST IT WITH DIFFERENT DATA. 



1 check_back_issues 
















1 from (specify vol:num): 2:1 














I to (specify vol:num 


:3:1 














i volume 1 number 


1 














j stocked: 23 


outstanding 


requests: 





cost 


of 


this 


issue: 1 


I $5.00. 
















! volume 1 number 


2 














i stocked: 30 


outstanding 


requests: 


2 


cost 


of 


this 


issue: 1 


I $3.00. 
















! volume 1 number 


3 














I stocked: 27 


outstanding 


requests: 





cost 


of 


this 


issue: | 


1 $3.00. 
















I volume 1 number 


4 














! stocked: 20 


outstanding 


requests: 


1 


cost 


of 


this 


issue: I 


1 $3.00. 
















! volume 1 number 


5 














1 stocked: 40 


outstanding 


requests: 





cost 


of 


this 


issue: 1 


1 $3.00. 
















! volume 1 number 


5 














I stocked: 35 


outstanding 


requests: 


4 


cost 


of 


this 


issue: I 


1 $3.00. 
















S volume 2 number 


1 














! stocked: 30 


outstanding 


requests: 


2 


cost 


of 


this 


issue: I 


1 $3.00. 
















1 number of issues stocked: 205 














1 number of requests i 


oending : 


9 












1 total stock value: 


$661.00. 














1 r. 09:13 0.443 96 
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a ONE MORE BREAK CONTROL REQUEST 



I THE continue to REQUEST 



I CAUSES probe TO CONTINUE EXECUTING, BUT ONLY UNTIL LINE 
SPECIFIED 



I USAGE : 

continue_to <line> 
ct <line> 

I EXAMPLES: 

continue to 75 
ct +1 



I NOTES: 

THE FIRST EXAMPLE RESUMES EXECUTION OF THE PROGRAM AND STOPS 
IN probe AT LINE 75 OF THE PROGRAM 

THE SECOND EXAMPLE RESUMES EXECUTION, BUT STOPS BEFORE THE 
NEXT STATEMENT (I.E. EXECUTE ONE STATEMENT); SEE THE stsp 
REQUEST LATER 
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probe check_back_issues 

Using check_back_ issues (no active frame) . 

position pos"ition_f ile 

position_f ile: 

proc (first_vol, first_num); 
a 

Break set after line 129 
status 

Break exists after line 129 in check_back_issues 
a 
r 09:20 0.311 120 

check_back_ issues 

from (specify vol:num): 2:1 

to (specify vol:num):3:l 

Stopped after line 129 of position_f ile. (level 8) 
v first vol 
first_vol = 2 
v first num 
first_num = 1. 
•ps +3 

end; 
a 

Break set after line 146 
continue_to 132 

probe (continue to): Using line 144 of check_back_issues instead. 
Stopped before Tine 144 of position file, (level If) 
sc 

do while (first vol > current volume) ; 
v first vol 
first_vol = 2 
v current_volume 
current_volume = 4.30337e9 
sb current_volume 

fixed bin (17) automatic 
Declared in check back issues 
q 

r 09:25 0.831 265 
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qedx 

rcheck_back_issues.pll 

/del (current_volume/ 

del (current_volume, current_number) fixed bin; 

s/;/ init (0T;/p 

del (current_volume, current_number) fixed bin init (0); 

w 

q 

r 09:27 0.288 83 

pll check_back_issues -sv2 -tb 

PL/I 26a 

r 09:27 3.520 230 

close__file back_issues 
r 09:28 0.044 48 
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check back issues 

from (specify vol:num):2:l 

to {specify vol:num):3:l 

volume 2 number 2 

stocked: 36 outstanding requests: 1 cost of this issue: 
$3.00. 

volume 2 number 3 

stocked: 46 outstanding reauests: 7 cost of this issue; 
$3.00. 

volume 2 number 4 

stocked: 31 outstanding requests: cost of this issue 
$3.00. 

volume 2 number 5 

stocked: 36 outstanding requests: cost of this issue: 
$3.00. 

volume 2 number 5 

stocked: 33 outstanding requests: 1 cost of this issue: 
$3.00. 

volume 3 number 1 

stocked: 47 outstanding requests: 5 cost of this issue: 
$3.00. 

volume 3 number 2 

stocked: 50 outstanding requests: 4 cost of this issue: 
$3.00. 

number of issues stocked: 279 
number of requests pending: 18 
total stock value: $837.00. 
r 09:28 0.395 30 



a TWO MORE BREAK REQUESTS 

I THE reset REQUEST 

I DELETES SPECIFIED BREAKPOINTS 

(RESET BEING A HARDWARE TERM FOR TURNING A SWITCH OFF) 
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I USAGE: 
reset 
r 

reset <location> 
r <location> 
reset <program name) 
r <program name> 
reset -all 
r -all 
reset * 
r * 

I EXAMPLES: 

reset after 75 

reset 

reset other-prog 

r * 

I NOTES: 

THE "reset *" and "reset -all" ARE IDENTICAL: THEY BOTH 
DELETE ALL BREAKPOINTS IN ALL PROGRAMS 



I THE step REQUEST 



I EXECUTES ALL THE INSTRUCTIONS UP TO, BUT NOT INCLUDING, THE 
NEXT STATEMENT 



I USAGE : 
step 
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I EXAMPLES: 
step 
s 

I NOTES: 

ACTS JUST LIKE EITHER OF THE FOLLOWING: 

continue_to +1 

before +1: (reset; halt) 
IS DEFINITELY MORE CONVENIENT 
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i ■ ■ ■ r 

i i 

pb check_back__issues 

Using check back issues (no active frame) . 

ps position~£ ile 

position fiTe: 

proc (first__vol, first_num); 
a ~* 

Break set after line 129 

q 

r 09:30 0.247 98 

check_back issues 

from (specTfy vol:num): 2:1 

to (specify vol :nura) : 3: 1 

Stopped after line 129 of position_f ile. (level 8) 

sk 8,2 

8 position_f ile (line 129) 

7 check_back_issues (line 58) 

sc 

position file: 

proc (first_vol, f irst_num) ; 

step 

Stopped before line 144 of posi tion_f ile . (level 8) 

sc 

do while (first_vol > current_volume) ; 

ps "return" 
return; 

b 

Break set before line 152 
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status 

Break exists before line 152 in check_back_issues 
Break exists before line 144 in check_back__issues 
Break exists after line 129 in check_back Tssues 

reset 144 

Break reset before line 144 in check_back_issues 

continue 

Stopped before line 152 of position_f ile. (level 8) 

v current volume 
current_volume = 2 

v current_number 
current number = i 

q 

r 09:39 1.492 420 
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I TECHNIQUE 



I DETERMINE THAT CORRECT NUMBER OF RECORDS ARE BEING PRINTED 
OUT, BUT THAT THE STARTING POINT IS INCORRECT 



I DECIDE THAT THE PROGRAM "position file" IS THE PROCEDURE THAT 
SETS THE STARTING POINT 



1 SET BREAKPOINTS WITHIN " poS 1 1 Ion £ 1 le" TO CHECK THE SiSTTINCj 
OF THE STARTING POINT 



I SEE THAT "position file" POSITIONS TO THE FIRST DESIRED 
RECORD 



I CONCLUDE THAT "print record" DOES NOT HAVE TO READ THE FIRST 
RECORD ~ 
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qx 

rcheck_back_issues.pll 
/call get_record/ 

call get record () ; 



\f 

/return/ 

-1 
a 



if have used record then 



return; 



have used record = "l"b; 



\f 
a 

\f 

/position_f ile/ 

posi tion f ile : 
/return/ 

return; 
-1 

a 

have used_record = "0"b; 

\f 

ln/dcl/ 

del back_issues file; 

i 

del have_used record bit (1) aligned; 

\f 

w 

q 

r 09:43 0.637 104 

pll check_back_issues -sv2 -tb 

PL/I 26a 

r 09:43 3.814 183 
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1 

1 close file back issues 












1 


1 r 09:43 0.050 29 
















1 check back issues 
















1 from (specify vol:num) 


:2sl 












1 to (specify vol:num 


:3:1 














i volume 2 number 


i 














1 stocked: 30 


outstand ing 


requests: 


2 


cost 


of 


this 


issue: [ 


1 $3.00. 
















1 volume 2 number 


2 














1 stocked: 36 


outstanding 


requests: 


1 


cost 


of 


this 


issue : I 


1 $3.00. 
















1 volume 2 number 


3 














1 stocked: 46 


outstand ing 


requests: 


7 


cost 


of 


this 


issue: 1 


1 $3.00. 
















1 volume 2 number 


4 














1 stocked: 31 


outstanding 


requests: 


• 


cost 


of 


this 


issue: ! 


1 $3.00. 
















1 volume 2 number 


5 














! stocked: 36 


outstanding 


requests: 





cost 


of 


this 


issue: I 


1 $3.00. 
















I volume 2 number 


6 














1 stocked: 33 


outstanding 


requests: 


1 


cost 


of 


this 


issue: | 


1 $3.00. 
















1 volume 3 number 


1 














1 stocked: 47 


outstanding 


requests: 


5 


• cost 


of 


this 


issue : I 


1 $3.00. 
















1 number of issues stocked: 259 












1 number of requests 


pending : 


16 












1 total stock value: 


$777.00- 














1 r 09:44 0.459 14 
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PROBE ODDS AND ENDS 

B A FEW MORE COMMANDS 

I THE halt REQUEST 

I CAUSES PROBE TO BE ENTERED AT BREAKPOINT EXECUTION TIME 

I USAGE: 
halt 

h 

I EXAMPLES: 

halt 
h 

I NOTES: 

ONLY USEFUL IF NOT EXECUTING IN PROBE ALREADY 

A BREAKPOINT SET IN THE FORM OF "after" IS REALLY 

I THE pause REQUEST 

I ACTS LIKE THE halt REQUEST, BUT ALSO RESETS THE BREAKPOINT 

I USAGE: 
pause 

P 
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I EXAMPLE: 
pause 

P 

I NOTES: 

LIKE THE halt REQUEST, IS ONLY USEFUL AT A BREAKPOINT 

the BREAKPOINT " after :pause" IS EQUIVALENT TO "after: 
(halt;reset) " 

I THE listjauiltins REQUEST 

I LISTS THE BUILTIN FUNCTIONS AVAILABLE FROM WITHIN probe 

I USAGE: 

list^builtins 
lb 

I EXAMPLES: 

1 ist_builtins 
lb 

I THE list help REQUEST 



I LISTS ALL THE HELP FILES AVAILABLE THROUGH THE probe "help" 
REQUEST 



I USAGE: list_help 
Ih 
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I EXAMPLES: 

list help 

lh 

NOTES : 

YOU CAN GET MORE THAN JUST HELP ON THE REQUESTS; 
DESCRIPTIONS ARE ALSO PROVIDED FOR THE ARGUMENTS TO probe 
REQUESTS 



a SPECIFYING LINES 

I SEVERAL PROBE REQUESTS ACCEPT LINE NUMBERS AS THEIR ARGUMENTS 
I before 
i after 
■I reset 
I status 

I SPECIFICATION OF A LINE CAN TAKE ON MANY FORMS 

I ABSOLUTE LINE NUMBER 

5 

xuu 

4-21 

I RELATIVE EXECUTABLE STATEMENT 

+ 1 
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+ 50 




-5 


I 


USING LABELS 




get_record 




place (3) 




somewhere,4 




$100 


I 


SPECIAL SYMBOLS 




$c 




Sc,7 




$b 




$b,3 
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TOPIC III 



Other Source-Level Debugging Commands . 3-1 

The trace Command _.. 3-1 

Interaction of the Control Arguments 3-5 

Tracing Example One . 3-6 

Other trace Control Requests 3-11 

Trace Example Two 3-14 

The display pllio error Command 3-20 

A display pllio error Example 3-21 



3-i 



Topic III SOURCE-LEVEL DEBUGGING (TRACE) Topic HI 



OBJECTIVES: 



Upon completion of this topic* students should be able to: 



1. Add and remove procedures to and from the trace table. 



2. Modify the tracing of a particular procedure in the traci 



3. Use the trace command to perform metering on selected 
procedures. 



4. Monitor recursion of selected procedures. 
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THE TRACE COMMAND 



b trace COMMAND 

I SOURCE-LEVEL, PROCEDURE-CALL MONITOR 

I CAN BE USED WITH PROGRAMS WHICH DO NOT HAVE SYMBOL TABLES 

I CAPABILITIES INCLUDE 

I PRINTING ARGUMENTS AT PROCEDURE ENTRY AND/OR EXIT 



I EXECUTING A MULTICS COMMAND LINE AT PROCEDURE ENTRY AND/OR 
EXIT 



I STOPPING (BY CALLING THE COMMAND PROCESSOR) AT PROCEDURE 
ENTRY AND/OR EXIT 



I CONTROLLING THE FREQUENCY AT WHICH TRACING MESSAGES ARE 
PRINTED 



I WATCHING UP TO 16 STORAGE LOCATIONS FOR CHANGES .AT EVERY 
PROCEDURE ENTRY AND/OR EXIT 



I LIMITATIONS 



I ONLY EXTERNAL PROCEDURES COMPILED BY PL/I OR FORTRAN CAN BE 
TRACED 



I ONLY USER-RING PROCEDURES CAN BE TRACED, NOT SUPERVISOR OR 
GATE PROCEDURES 
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THE TRACE COMMAND 



I A PROCEDURE IN A BOUND SEGMENT CAN BE TRACED ONLY IF ITS 
uNinj ruiiNi n^.s oc&N ft&iAiiscD iN ini, ouuNu s cui'it in T 



I USAGE 

trace -control__args 

OR 
trace procedure__names 

OR 
trace -control_args procedure_names 

I procedure_names GIVE THE PATHNAME OR REFERENCE NAME OF A 
PROCEDURE ENTRY POINT TO 3E TRACED 

Jirectory_path>entryname 

d irectory_path>entryname$entry_po int_name 

?e£erence_name 

ref erence_name$entry_point_name 

I control_args CONTROL THE TRACING FUNCTIONS PERFORMED ON THE 
TRACED PROCEDURE 



I OPERATION 

I trace COUNTS 

I HOW MANY TIMES A PROCEDURE IS CALLED (N = NUMBER OF CALLS) 
IN THIS PROCESS SINCE COUNTERS WERE LAST RESET 

I HOW MANY TIMES A PROCEDURE IS MONITORED WHILE A PREVIOUS 
ACTIVATION STILL EXISTS (R = RECURSION DEPTH) 
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I OPERATION (Continued) 

I trace MONITORS A PROCEDURE CALL 

I WHEN N AND R MEET CERTAIN CRITERIA 

I BY PRINTING MONITORING MESSAGES 

Call N.R of PROCEDURE from CALLING_PROC , ap=244|1746. 

Return N.R from PROCEDURE. 

I BY OPTIONALLY PRINTING PROCEDURE ARGUMENTS BEFORE ENTRY OR 
AFTER EXIT 

I BY OPTIONALLY GOING TO Multics COMMAND LEVEL OR INVOKING A 
USER-SPECIFIED PROCEDURE BEFORE ENTRY OR AFTER EXIT 

I MONITORING CRITERIA 

I ARE STORED IN A TRACE CONTROL TEMPLATE (TCT) , AN INTERNAL 
STATIC DATABASE IN THE PROCESS DIRECTORY 

I FOR EACH TRACED PROCEDURE ARE STORED IN TEMPLATES 
FASHIONED AFTER THE TCT 

I IN THE TCT ARE PRINTED BY 

trace -template 

1 ARE SET BY GIVING A trace COMMAND WITH THE FOLLOWING 
control_args: 

-first F, -ft F 

MONITOR WHEN F<=N 

-last L, -It L 

MONITOR WHILE N<=L 

-every E, -ev E 

MONITOR EVERY Eth CALL (WHEN mod(N,E)=0) 

-before B 

STOP BEFORE ENTERING PROCEDURE IF B~=0 AND mod(N,3)=0 
AND mod(N,E)=0 

-after A 

STOP AFTER EXITING PROCEDURE IF A~ = AND mod-(N,A)=0 
AND mod(N,E)=0 
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-argument AG, -ag AG 
mod(N,E)=0 

-in PRINT ARGUMENTS ONLY BEFORE ENTRY 
-out PRINT ARGUMENTS ONLY AFTER EXIT 

-inout 

PRINT ARGUMENTS BEFORE ENTRY AND AFTER EXIT 

-depth D, -dh D 

MONITOR ONLY IF R<=D AND GOVERNING IS OFF 

-return__value {onloff}, -rv {onloff} 

PRINT FUNCTION RETURN VALUE AFTER EXIT 

-govern {onloff}, -gv {onloff} 

DISABLE RECURSION DEPTH CHECKING; INSTEAD, PRINT THE 
CALL MESSAGE ONLY WHEN THE RECURSION DEPTH REACHES A 
NEW MAXIMUM. ALSO, STOP WHEN RECURSION DEPTH IS A 
MULTIPLE OF 10 & A NEW MAXIMUM. 

-meter {onloff}, -mt {onloff} 

DISABLE MONITORING AND ENABLE PERFORMANCE METERING OF 
THE TRACED PROCEDURES 
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INTERACTION OF THE CONTROL ARGUMENTS 



tract -firtt 5 -last 12 -«wy 2 -before 3 -argument 4 



CALLS OF tt 

(N) 



O000 




MONITOR EVERY 
2nd CALL 
(-every 2) 




^W^^^H^H^ 



6.1 8.2 10.3 12.4 



STOP BEFORE 
EVERY 3rd CALL 

{-before 3) 



1 




10 



PRINT INPUT 
ARGUMENTS EVERY 
4th CALL (IF IT'S 
MONITORED) 
(•argument 45 



1 



1 



12 
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TRACING EXAMPLE ONE 



1 

] 

1 1 


fact 


• 


i 

i 

procedure (n) returns (fixed dec (12)); 1 


1 2 


del 


(n 


, f 


, r) fixed dec (12) ; 1 


1 3 








if n <= 1 tnen r - 1; 1 


! 4 








else do; " 1 


1 5 








f = fact (n-1) ', 1 


1 6 








r = f * n; 1 


1 7 








end; I 


1 8 








return ( r) ; 1 


1 9 




end 


fact ; | 













1 factorial: procedure; 

2 del result fixed dec (12); 

3 del fact_ entry (fixed dec 12)) returns (fixed dec (12) 

4 del n fixed dec (12); 

5 del cleanup condition; 

6 del (sysin, sysprint) file? 

7 open file(sysin) stream input, 

8 f ile(sysprint) stream output 

9 env ( interactive) ; 

10 on cleanup close file (sysin) , file (sysprint); 

11 get file (sysin) list (n); 

12 do while (n >= 0) ; 

13 result = fact_ (r^ ; 

14 put file (sysprint) list (result); 

15 get file (sysin) list (n); 

16 end; 

17 close file (sysin), file (sysprint); 

18 end factorial; 
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! 1 


! pll fact 




1 2 


PL/I 






1 "3 
1 -J 


r 1720 


1.381 21.776 148 




I 4 








! 5 


! pll factorial 




! 6 


PL/I 






I 7 


r 1720 


0.964 1.332 36 




1 8 








! 9 


I factorial 




1 10 


i 3 






1 11 




6 




1 12 


1 4 






1 13 




24 




! 14 


i 5 






1 15 




120 




1 16 


i 5 






! 17 




7 20 




1 18 


! 10 






1 19 




3628800 




1 20 


! -1 






j 21 


r 1721 


0.303 0.342 18 




I 22 
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TRACING EXAMPLE ONE 



23 ! trace -template 

24 first: 1, last: 9999999999, every: 1, 

2"^ heforp. n_ aff-or- n. srn5- Q. risarii-h> qqqqqqqqqq 

26 meter: off, govern: off, return_value off 

27 r 1721 0.067 0.042 6 
28 

29 I trace -arguments 1 -out -return_value on 

30 r 1721 0.038 0.002 1 
31 
32 
33 
34 
3b 
36 

37 Call 1.1 of fact from factorial 1 235 , ap = 24415254 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 



I trace fact 






r 1721 


0.155 0.506 22 






! factorial 






1 5 N % 


^ 






Call 1, 


1 of fact_ from 


factoriall 235, 


ap = 244 


Call 2 


2 of fact_ from 


fact 143, ap = 


24415600 


Call 3. 


3 of fact_ from 


fact_| 43, ap = 


24416120 


Call 4 


4 of fact_ from 


fact_| 43, ap = 


24416440 


Call 5. 


5 of fact_ from 


fact 143, ap = 


24416760 


Return 


5.5 from fact 






ARG 1 


§ 244 16750 = 1 






ARG 2 


@ 24416740 = 1 






Return 


4.4 from fact 






ARG 1 


§ 24416430 = 2 






ARG 2 


§ 24416420 = 2 






Return 


3.3 from fact 






ARG 1 


@ 24416110 = 3 






ARG 2 


6 24416100 = 6 






Return 


2.2 from fact 






ARG 1 


@ 24415570 = 4 






ARG 2 


@ 24415560 = 24 






Return 


1.1 from fact 






ARG 1 


§ 24415144 = 5 






ARG 2 


@ 24415140 = 120 






120 






! -1 








r 1721 


0.395 1.632 47 
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TRACING EXAMPLE ONE 



61 I trace -every 3 

62 r 1722 0.021 0.000 
63 

64 ! trace fact_ 

65 r 1722 0.024 0.000 
66 

67 ! factorial 

68 ! 10 

69 Call 6.1 of fact_ from factorial I 235 , ap = 24415254 

70 Call 9.2 of fact_ from fact_l43, ap = 24416100 

71 Call 12.3 of fact_ from fact_j43, ap = 24416720 

72 Call 15.4 of fact_ from fact_|43, ap = 24417540 

73 Return 15.4 from fact_ 

74 ARG 1 @ 24417530 = 1 

75 ARG 2 § 24417520 = 1 

76 Return 12.3 from fact_ 

77 ARG 1 @ 244 16710 = 4 

78 ARG 2 @ 244 16700 = 24 

79 Return 9.2 from fact_ 

80 ARG 1 @ 244 16070 = 7 

81 ARG 2 @ 244 16060 = 5040 
32 Return 6.1 from fact_ 

83 ARG 1 @ 24415144 = 10 

84 ARG 2 § 244 15140 = 3628800 

85 3628800 

86 ! -1 

37 r 1722 0.210 0.002 1 
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89 ! trace -status fact_ 

90 fact_: 

91 N ■ 15 

92 R - , max R = 

93 P - 1 

94 L » 9999999999 

95 E ■ 3 

96 B - 

97 A ■ 

98 AG = l(o) 

99 D » 9999999999 
100 return_value 
101 

102 r 1722 0.052 0.000 
103 

104 ! trace -status * 

105 15.0 fact_ 

106 r 1723 0.027 0.000 
107 

108 I trace -reset fact_ -status fact_ 

109 ' fact_: 

110 N = 

111 R = 0, max R = 

112 F - 1 

113 L = 9999999999 

114 E » 3 

115 B = 

116 A = 

117 AG = 1(0) 

118 D = 9999999999 

119 return_value 
120 

121 r 1723 0.055 0.006 2 
122 

123 1 factorial 

124 ! 4 

125 Call 3.1 of fact_ from fact_|43, ap = 24415560 

126 Return 3.1 from fact_ 

127 ARG 1 § 24415550 - 2 

128 ARG 2 § 244 15540 = 2 

129 24 

130 1 -1 

131 r 1724 0.103 0.000 
132 
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OTHER TRACE CONTROL REQUESTS 
I OTHER trace CONTROL ARGUMENTS 

I CONTROL THE GENERAL OPERATION OF trace 

I INCLUDE 

-status procedure_name, -st procedure_name 

PRINTS THE TRACE CONTROL PARAMETERS AND COUNTERS FOR THE 
NAMED PROCEDURE 

-status *, -st * 

LISTS THE PROCEDURES BEING TRACED, THEIR INVOCATION 
COUNTS AND RECURSION DEPTHS 

-reset procedure_name, -rs procedure_name 

ZEROES THE INVOCATION COUNT OF THE GIVEN PROCEDURE 

-off procedure_name 

STOPS MONITORING THE GIVEN PROCEDURE; PROCEDURE REMAINS 
IN TRACE TABLE AND COUNTING OF INVOCATIONS CONTINUES, 
HOWEVER 

-on procedure_name 

RESUMES MONITORING THE GIVEN PROCEDURE 

-remove procedure_name, -rm procedure_name 

STOPS TRACING THE GIVEN PROCEDURE, DELETING ALL COUNTERS 
FOR THE PROCEDURE 



I THE procedure_name OPERAND FOLLOWING CONTROL ARGUMENTS MUST 
HAVE THE FORM: 

entryname 

entryname$entry_point_name 

reference_name 

ref erence_name$entry_point_name 



THE CONTROL ARGUMENT APPLIES TO ALL TRACED PROCEDURES WHEN * 
IS GIVEN 
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OTHER TRACE CONTROL REQUESTS 



1 133 


1 134 


1 135 


! 136 


1 137 


1 138 


I 139 


1 140 


1 141 


! 142 


I 143 


i 144 


1 145 


1 146 


! 147 


t 148 


] 149 


1 150 


1 151 


1 152 


1 153 


1 154 


i 155 


1 156 


1 157 


1 158 


i 159 


1 160 


1" 161 


1 162 


1 163 


1 164 


1 165 


i 166 


1 167 


1 168 


I 169 


1 170 



trace -off fact_ 

r 1724 0.0.22 0.000 



i \2 

479001600 
I -1 

X 1725 0.072 0.000 

! trace -on fact_ 

r 1725 0.025 0.000 

! factorial 
! 2 

Call 18.1 of fact_ from fact_|43, ap = 24415420 

Return 18.1 from fact__ 

ARG 1 8 244 15410 = 1 

ARG 2 § 244 15400 = 1 
2 
I -1 

r 1726 0.055 0.000 

! trace -status * 
18.0 fact_ 
r 1726 0.028 0.000 

1 trace -remove fact_ 
r 1726 0.027 0.002 1 

I trace -status * 

trace: Trace table is empty, 
r 1727 0.036 0.000 

i factorial 
1 1Q 

3628800 
! -1 

r 1727 0.070 0.000 
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OTHER TRACE CONTROL REQUESTS 
I OTHER trace CONTROL ARGUMENTS 



I CONTROL THE GENERAL OPERATION OF trace 

-brief, -bf 

SHORTENS THE MONITOR MESSAGES 

-long, -Ig 

PRINTS LONGER MONITOR MESSAGES AGAIN 

-io_switch swi tch__name, -is switch_name 

PRINTS MONITOR MESSAGES ON THE NAMED I/O SWITCH, WHICH 
MUST BE ATTACHED & OPENED FOR STREAM_QUTPUT 

-execute command_line, -ex command_l ine 

EXECUTES THE COMMAND LINE WHENEVER A PROCEDURE IS 
MONITORED 

-stop_proc procedure_name, -sp procedure_name 

CHANGES THE PROCEDURE CALLED TO STOP BEFORE ENTRY OR 
AFTER EXIT TO THE GIVEN PROCEDURE 



I CONTROL PERFORMANCE MONITORING 

-meter {onloff}, -mt {on|off} 

STARTS/STOPS METERING OF TRACED PROCEDURES 

-total- -tt 

PRINTS PERFORMANCE MEASUREMENTS AND CLEARS THE METERING 
STATISTICS 

-subtotal, -stt 

PRINTS PERFORMANCE MEASUREMENTS BUT DOES NOT CLEAR THE 
METERING STATISTICS 

/X/ y — r (X Co>vv^avx5^ 

I WATCH STORAGE LOCATIONS FOR CHANGES AS PROCEDURES ARE TRACED 
AND STOP IF THE LOCATIONS CHANGE 

-watch location, -wt location 

WATCHES THE ONE WORD LOCATION. UP TO 16 LOCATIONS CAN 
BE WATCHED AT ANY TIME. location HAS THE FORM: 

segment number I of f set 



-watch off, -wt off 

TURNS OFF THE WATCH FACILITY 
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TRACE EXAxMPLE TWO 



1 , 


I. print tt.pll 1 • 




2 


tt: proc; 




3 


del ioa entry options (variable) ; 




4 


del d$ external static; 




5 


del mod builtin; 




6 


del cleanup condition; 




7 


on cleanup begin; 




8 


counter = 0; 




9 


call ioa ("counter initialized back to zero."); 




10 


goto bottom; 




11 


end; 




12 


del counter fixed bin internal static init (0); 




13 


counter = counter +1; 




14 


call ioa_ ("..~i", counter); 




15 


if mod (counter, 5) = then d$ = counter; 




16 


call tt; 




17 


bottom : 




18 


end tt; 




19 






20 






21 


! trace -ft 5 -last 12 -every 2 -before 3 -argument 4 tt 




22 


I trace -status tt 




23 


tt: 




24 


N = 




25 


R = 0, max R = 




26 


F ■ 5 




27 


L = 12 




28 


E = 2 




29 


B » 3 




30 


A = 




31 


AG = 4 




32 


D = 9999999999 




33 






34 


! trace -template 




35 


first: 5, last: 12, every: 2, before: 3, after: 0, args: 


4, 


36 


depth: 9999999999, meter: off, govern: off, return_value 


off 


37 


i tt 




38 


. .1 ■ 




39 


..2 




40 


..3 




41 


..4 




42 


. .5 




43 


Call 6.1 of tt from tt|113, ap - 24415476 




44 


trace: stop before 




45 


! hmu 




46 






47 


Multics MR6.5+, load 32.0/150.0; 40 users 




48 


Absentee users 0/4 




49 






50 


! start 




51 


. .6 




52 


..7 




53 


Call 8.2 of tt from tt|113, ap = 24416156 




54 


No arguments. 




55 


..8 




56 


..9 




57 


Call 10.3 of tt from tt|113, ap = 24416636 
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TRACE EXAMPLE TWO 

58 ..10 

59 ..11 

60 Call 12.4 of tt from tt|113, ap = 24417316 

61 No arguments. 

62 trace: stop before 

63 ! sr 

64 ..12 

65 ..13 

66 ..14 

67 ..15 

68 ..16 

69 ..17 

70 ..18 

71 ..19 

72 ..20 

73 QUIT 

74 I trace -status tt 

75 tt: 

76 N = 282 

77 R = 4, max R = 

78 F = 5 

79 L = 12 

80 E = 2 

81 3 = 3 

82 A ■ 

83 ' AG = 4 

34 D = 9999999999 

85 

86 ! release -all 

87 counter initialized back to zero. 

88 Return 12.4 from tt 
39 Return 10.3 from tt 

90 Return 8.2 from tt 

91 Return 6.1 from tt 

92 i trace -status tt 

93 tt: 

94 N = 282 

95 R = Q , max R = 

96 F = 5 

97 L = 12 

98 E = 2 

99 B. * 3 

100 A = 

101 AG = 4 

102 D = 9999999999 
103 

104 ! .1 tracerev 

105 b tracerev trace -ft 1 -It 9999999999 -ev 1 -before 

106 -after -ag -dh 9999999999 -mt off -gv off -wt off 

107 -return_value off 

108 ! tracerev tt 

109 ! trace -st tt 

110 tt: 

111 N » 282 

112 R = 0, max R = 

113 F = 1 

114 L = 9999999999 
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TRACE EXAMPLE TWO 



115 

116" 

117 

118 

119 

120 

121 

122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 

133 

134 

135 

136 

137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 

161 

162 

163 

164 

165 

166 

167 

168 

169 

170 

171 



. E = 1 

B »'0 

A = 
AG = 

D = 9999999999 



1 list ref names d 



357 



= 000000000012 
from tt|113, ap 



= 244110576 



trace -watch 35710 
trace tt 
tt 
..1 
..2 
. .3 
..A 
. .5 

trace_print_: 357 10 = 000000000005 
Call 288.6 of tt from tt|113, ap = 24416556 
trace: stop before 
1 start 
..6 
..7 
..8 
..9 
. .10 

trace_print_: 357 
Call 293.11 of tt 
trace: stop before 
1 start 
..11 
..12 
..13 
. .14 
..15 

trace_print_: 357|0 = 000000000017 
Call 298.16 of tt from tt|113, ap = 244112616 
trace: stop before 
I rl -all 

counter initialized 
1 tracerev tt 
t trace -st tt 
tt : 

N 

R 

F 

L 

E 

B 

A 
AG 

D 



back to zero 



R = 



= 298 
= 0, max 

- 1 

= 9999999999 

- 1 
a 
* 
= 

= 9999999999 



trace -reset tt 
trace -govern on tt 
tt 
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TRACE EXAMPLE TWO 

172 Call 1.1 of tt from command_processor_J 3304 (read list), 

ap = 24414600 

173 ..1 

174 Call 2.2 of tt from tt|113, ap = 24415056 

175 ..2 

176 Call 3.3 of tt from tt|113, ap = 24415376 

177 ..3 

178 Call 4.4 of tt from tt|113, ap = 24415716 

179 ..4 

180 Call 5.5 of tt from tt|113, ap = 24416236 

181 ..5 

182 trace_print_: 357 [0 =000000000005 

183 Call 6.6 of tt from tt|113, ap = 24416556 

184 ..6 

185 Call 7.7 of tt from tt|113, ap = 24417076 

186 ..7 

187 Call 8.8 of tt from tt|113, ap = 24417416 

188 ..8 

189 Call 9.9 of tt from tt|113, ap = 24417736 

190 ..9 

191 Call 10.10 of tt from tt|113, ap = 244110256 

192 trace: stop before 

193 I trace -brief tt 

194 ! start 

195 ..10 

196 trace_print_: 35710 ■ 000000000012 

197 Call 11.11 of tt 

198 ..11 

199 Call 12.12 of tt 

200 ..12 

201 Call 13.13 of tt 

202 ..13 

203 Call 14.14 of tt 

204 ..14 

205 Call 15.15 of tt - 

206 ..15 

207 trace_orint_: 357 10 = 000000000017 

208 Call 16.16- of tt 

209 ..16 

210 Call 17.17 of tt 

211 ..17 

212 Call 18.18 of tt 

213 ..18 

214 Call 19.19 of tt 

215 ..19 

216 Call 20.20 of tt 

217 trace: stop before 

218 QUIT 

219 » trace -watch off tt 

220 ! sr 

221 i ready 

222 r 1842 9.009 21.098 724 level 2, 51 
223 

224 i sr 

225 ..20 

226 Call 21.21 of tt 

227 ..21 
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TRACE EXAMPLE TWO 



228 


Call 


22, 


22 of 


tt 




229 


..22 










230 


Call 


23. 


,23 of 


tt 




231 


. .23 










232 


Call 


24. 


,24 of 


tt 




<-» *■» *^ 


«, . 24 










234 


Call 


25. 


,25 of 


tt 




235 


„ .25 










236 


Call 


26. 


, 26 of 


tt 




237 


..26 










238 


Call 


27, 


.27 of 


tt 




239 


• p &> f 










240 


Call 


28. 


.28 of 


tt 




241 


. . 28 










242 


Call 


29. 


,29 of 


tt 




243 


« • £e .7 










244 


Call 


30. 


.30 of 


tt 




245 


trace: stop before 




246 


QUIT 










247 


! rl 


-all 






248 


counter 


initialized back 


to zero. 


249 


! trace 


-st tt 




250 


tt : 










251 






N = 


30 




252 






R = 


0, max R = 


30 


253 






F = 


1 




254 






L = 


9999999999 




255 






E = 


1 




256 






. B ■ 







257 






A = 







258 






AG » 







259 






D = 


9999999999 




260 






govern 




261 












262 


! trace 


-govern off tt 




263 


! trace 


-St ti 


: 




264 


tt: 










265 






N = 


30 




266 






R = 


, max R = 


30 


267 






F = 


1 




268 






L = 


9999999999 




269 






E - 


I 




270 






B = 







271 






A = 







272 






AG = 







273 






D - 


9999999999 




274 












275 


! trace 


-reset tt 




276 


! 'trace 


-st tt 




277 


tt: 










27 8 






N = 







279 






R = 


, max R = 


30 


280 






F = 


1 




281 






L = 


9999999999 




282 






E = 


1 




283 






B = 







284 






A = 
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TRACE EXAMPLE TWO 
28 5 AG = 

286 D = 9999999999 



Not To Be Reproduced 3-19 F21 



THE DISPLAY PL1I0 ERROR COMMAND 



•» displ"ay_pll ; .o_error ■ COMMAND 



I PRINTS ADDITIONAL INFORMATION ABOUT THE MOST RECENT ERROR 
CONDITION SIGNALLED BY THE PL/1 INPUT/OUTPUT FACILITY 



I USAGE 

display_pllio_error 

OR 
dpe 

I PL/I I/O ERROR CONDITIONS INCLUDE 

I end file 

I key 

I name 

I recor- 

I transmit 

I undef inedf ile 
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A DISPLAY PL1I0 ERROR EXAMPLE 



1 1 

1 2 
1 3 


• 

write_f il 


e: procedure; ! 


del 


f fi 


le record output; 1 


1 4 


del 


reel 


char (10) , 1 


1 5 




rec2 


char (30) varying; 1 


1 6 
1 7 
1 8 


del 


cleanup condition; i 








1 9 






on cleanup close file ( f ) ; ! 


1 10 






open file ( f ) ; 1 


1 11 








1 12 






reel = "ABCDEfghi j " ; | 


1 13 






write file ( f ) from (reel); 1 


1 14 








[ 15 






rec2 = "abcdeFGHIJ"; 1 


1 16 






write file (f) from (rec2); 1 


1 17 








i 18 






close file ( f ) ; j 


I 19 








1 20 




end 


write_file; ! 



! 1 
1 2 
1 3 


r sad 


filo 


• ni' A/^a^iiya . 


_ 


del 


f fi 


le record input; 




! 4 


del 


svsorint filer 




! 5 


del 


reel 


char (10); 




1 6 
1 7 
1 8 


del 


(clea 


nup, endfile) condition; 








on cleanup close file ( f ) , file (sysprint) ; 




1 9 






open file ( f) , 




! 10 






file (sysprint) output stream env (interactive); 




I 11 










! 12 






on endfile ( f ) go to DONE; 




1 13 






do while ("l"b) ; 




1 14 






read file (f) into (reel); 




1 15 






put file (sysprint) list (reel); 




1 16 






end; 




1 17 










1 18 


DONE 


* 






1 19 






close file ( f ) , file (sysprint); 




I 20 










1 21 




end 


read_f ile; 
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A DISPLAY PL1I0 ERROR EXAMPLE 



1 ! pll read_file -table 

2 PL/I 

3 r 1033 1.353 37.579 272 
4 

5 S pll write_file -table 

6 PL/I 

7 r 1034 0.767 40.527 287 
8 

9 I read_file 
10 

11 Error: undefinedf ile condition 

12 by >udd>F19d>Friedman>read_f ilel 177 (line 9) 

13 occurred while doing i/o on file f 

14 File cannot be opened: call to iox_$open fails. 

15 system handler for error returns to command level 

16 r 1034 0.169 5.250 74 level 2, 16 
17 

18 i display_pll io_error 
19 

20 Error on file f, status code: Entry not found. 

21 Title: vfile_ f 

22 Attributes: input notkeyed record sequential 

23 Permanent attributes: input record 

24 Error in opening or closing f 

25 r 1035 0.069 1.470 37 level 2, 16 
26 

27 I probe 

28 Condition undefinedf ile raised at line 9 of read_file. 

29 ! source 

30 open file ( f) , 

31 file (sysprint) output stream env (interactive); 

32 ! quit 

33 r 1035 0.126 5.726 97 level 2, 16 
34 

35 I release 

36 r 1035 0.028 0.328 17 
37 
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A DISPLAY PL1I0 ERROR EXAMPLE 



38 ! write_file 
39 

40 Error: undef inedf ile condition 

41 by >udd>F19d>Friedman>write_file| 133 (line 10) 

42 occurred while doing I/O on file f 

43 File cannot be opened: 

44 .. input and output attributes conflict. 

45 system handler for error returns to command level 

46 r 1035 0.140 3.660 60 level 2, 16 
47 

48 I dpe 
49 

50 Error on file f 

51 Title: vfile_ f 

52 Attributes: input output record 

53 Permanent attributes: input output record 

54 Error in opening or closing f 

55 The output attribute conflicts with the input attribute. 

56 r 1036 0.061 1.190 34 level 2, 16 
57 

58 I new_proc 

59 r 1037 0.184 8.372 91 
60 

61 ! write_file 

62 r 1037 0=376 6.532 80 
63 

64 I read_file 
65 

66 Error: undef inedf ile condition 

67 by >udd>F19d>Friedman>read_f ilel 177 (line 9) 

68 occurred while doing I/O on file f 

69 File cannot be opened: 

70 input and output attributes conflict. 

71 system handler for error returns to command level 

72 r 1038 0.627 25.122 192 level 2, 16 
73 

7 4 ! new__proc 

75 r 1039 0.236 4.830 69 

76 
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A DISPLAY PL1I0 ERROR EXAMPLE 



77 J read_file 

78 ABCDEfghij 
79 

80 Error: record condition 

81 by >udd>F19d>Friedman>read_file| 241 (line 14) 

82 occurred while doing I/O on file f 

83 "read into (XX)"; 

84 record in data set larger than variable XX. 

85 Type "start" to continue. 

86 Data will be truncated to record's length. 

87 system handler for error returns to command level 

88 r 1039 0.887 25.244 219 level 2, 16 
89 

90 ! dpe 
91 

92 Error on file f, status code: Record is too long. 

93 Title: vfile_ f 

94 Attributes: open input notkeyed record sequential 

95 Permanent attributes: input record 

96 Last i/o operation attempted: read into 

97 r 1040 0.106 3.540 59 level 2, 16 
98 

99 ! probe 

100 Condition record raised at line 14 of read_file. 

101 I source 

102 read file ( f ) into (reel); 

103 ! v reel 

104 "\000\000\00Q 

105 abcdeF" 

106 ! quit 

107 r 1041 0.368 11.650 192 level 2, 16 
108 

109 I start 

110 \000\000\000 

111 abcdeF 

112 r 1041 0.119 3.492 59 
113 
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A DISPLAY PL1I0 ERROR EXAMPLE 



! 114 . 


print_attach_table f I 


i 115 


f (not attached) 1 


I 116 


r 1041 0.069 1.640 40 I 


1 117 




1 118 . 


io call attach f vfile f 1 


i 119 


r 1041 0.080 3.306 57 I 


1 120 




1 121 . 


io open f sequential input 1 


1 122 


r 1042 0.087 3.422 58 | 


I 123 




1 124 . 


io read_length f 1 


1 125 


io call: len=10. 1 


i 126 


r 1042 0.039 0.006 2 | 


1 127 




1 128 


io read f 10 . j 


1 129 


io call: 10 characters returned. ABCDEfghij | 


! 130 


r 1042 0.077 1.980 44 ~ 1 


I 131 




! 132 


io read_length £ 1 


1 133 


io call: len=34. ! 


! 134 


r 1042 0.032 1.332 36 ! 


1 135 




1 136 


io read f 40 1 


1 137 


io call: 34 characters returned. \000\000\000 ! 


1 138 


abcdeFGHIJ\4O0#\40O\000\000\000write file | 


i 139 


r_1042 0.050 1.980 44 ' ] 


! 140 




! 141 


IO (c1n!fl /lol-a^lil P | 


1 142 


r 1043 0.045 2.152 46 1 
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Topic IV ADVANCED PROBE REQUESTS Topic IV 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 

1. Use the followins probe requests to good advantage: 

modes 

if 

lansuase <ln9> 

display <ds> 

so to (s) 

where <wh> 

use 

call (cl) 

declare (del) 

list_variables (Isv) 
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INTRODUCTION 



a MORS ABOUT probe 



1 MOST DEBUGGING CAN BE DONE USING THE TECHNIQUES DESCRIBED IN 
CHAPTER TWO 



I THE REQUESTS DESCRIBED HERE GIVE THE USER MUCH MORE CONTROL OVER 



I THE CONTROL CAN BE THOUGHT OF AS COVERING DIFFERENT ASPECTS OF 
probe 

I CONTROL OF THE INTERACTION 
I modes 

I if 

I language 

I display 

I CONTROL OF PROGRAM USAGE 
I goto 
I where 
I use 
I call 

I CONTROL OF PROBE VARIABLES 
I declare 
I list variables 
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SCENARIO I - MORS PROBE CONTROL 

a NEW REQUESTS 

I THE modes REQUEST 

I ALTERS THE WAY probe INTERACTS WITH THE PROGRAMMER 

I USAGE: 
modes 
mode 

modes <mode type> <mode value> 
mode <mode type> <mode value> 

1 EXAMPLES: 

modes prompt on 

modes prompt string " pb: " 

mode value_separator " is equal to " 

I NOTES: 

SUPPORTED MODES ARE: 
error messages, em 
qualification, qf 
value_print, vp 
value_separator, vs 
prompt 
prompt string 
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SCENARIO I - MORE PROBE CONTROL 



I THE language REQUEST 

I ALLOWS THE PROGRAMMER TO LET probe INTERACT IN DIFFERENT 
DIALECTS 

I USAGES 
language 
Ing 

language <language> 
Ing <language> 

I EXAMPLES: 
language 
Ing 
language fortran 

I NOTES: 

THE LANGUAGES CURRENTLY SUPPORTED ARE pll , fortran, AND cobol 

I THE goto REQUEST 

I GIVES BETTER ERROR PROCESSING CONTROL 

I USAGE : 

goto <line> 
g <line> 

I EXAMPLES: 
goto 50 
g 1-23 
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SCENARIO I - MORE PROBE CONTROL 



g $c 
g $b+2 

I NOTES: 

I A TRICKY RQUEST TO USE 

I COMPILER OPTIMIZATION MAY NOT LET THE goto PERFORM AS IT 
SEEMS IT SHOULD 

I DEFINITELY MORE DEPENDABLE THAN COMMAND LEVEL start 



I THE SCENARIO - BACK TO OUR PROGRAM 
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SCENARIO I - MORE PROBE CONTROL 



r 13:57 0.332 51 

check_back__ issues 

from {specify vol:num) :1:1 
to (specify vol:num):2:l 

Error: conversion condition by 

>user_dir_dir>FSOEP>Pandolf>wkd>check_back_issues| 540 (line 4! 

onsource = "1:", onchar = " : " 

invalid character follows a numeric field. 

system handler for error returns to command level 

r 13:57 0.469 44 level 2 

pb 

Condition conversion raised at 

line 43 of check_back_issues (level 7). 

modes prompt true 

probe: language 

Current language is PL/I 

probe: sc 

f irst_issue_volume = 

substr (f irst_issue, 1, f irst_issue_del im) ; 
probe: modes prompt false 
modes prompt on 
probe: modes prompt off 

v substr (f irst_issue, 1, f irst_issue_delim) 
"1:" 

let f irst_issue__volume = "1" 
v f irst_issue_volume 
f irst_issue_volume = 1 

q 

r 14:01 0.431 61 level 2 
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SCENARIO I - MORE PROBE CONTROL 



start 

Error: conversion condition by 

>user_dir_dir>FSOEP>Pandolf>wkd>check_back_issuesj 540 (line 48-> 

onsource = "l:", onchar = ":" 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 14:01 0.257 3 level 2 

pb 

Condition conversion raised at 

line 43 of check_back_issues (level 7). 

v first issue delim 

first_issue delim = 2 

let f irst_issue_delim = 1 

v substr (first issue, 1, first issue delim) 

"1" ~ ~ 

q 

r 14:03 0.244 1 level 2 

start 

Error: conversion condition by 

>user_dir_dir>FSOEP>Pandolf>wkd>check_back_issues| 540 (line 48) 

onsource = "1 :", onchar = " : " 

Invalid character follows a numeric field. 

sys i_em usnuiSi i.cr error returns to comma nu isvsi 

r 14:03 0.235 level 2 

pb 

Condition conversion raised at line 48 of check back issues 

(level 7) . • - - 

v substr (f irst_issue , 1, first issue delim) 

n -I ii 

goto $c 

Error: conversion condition by 

>user_dir_dir>FSOEP>Pandolf>wkd>check back issues] 550 (line 

50) 

onsource = "2:", onchar = " : " 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 14:05 0.348 2 level 2 
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"CONTROL OF OUTPUT PROCESSING 



THE PREVIOUSLY DESCRIBED value REQUEST CAN BE USED TO DISPLAY A 
NAMED STORAGE LOCATION 



I THE display REQUEST 

I SHOWS ANY ACCESSIBLE LOCATION ON ONE OF FOUR FORMS 

I USAGE: 

display <address> <format> <count> 
ds <address> <format> <count> 

I EXAMPLES :- 

display var-one octal 2 
ds 260 114430 pointer 1 
ds tmp_strng ascii 12 

I NOTES: 

FOUR MODES ARE AVAILABLE 
octal, o 

ascii, a, character, ch, c 
instruction, i 



pointer, ptr, its 
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CONTROL OF OUTPUT PROCESSING 



I THE SCENARIO 



r 14:56 0.325 16 

check_back_issues 

from (specify vol:num): 1:1 

to (specify vol:num):l:4 

Error: illegal_procedure condition by 

>user_dir_dir>FSOEP>Pandolf>wkd>check back issues$print record! 675 

(line 96) 

(while in oil operator real_to_real_tr) 

referencing stack_4 15363 (in process dir) 

r 14:56 1.145 34 level 2 

pb 

Condition illegal_procedure raised at 

line 96 of print_record (level 8} . 

sc 

total_stock_value = 

total_stock_value + 
( issue_record.current__invento ry* 
'issue_record.cost_of_issue) ; 
v cost_of__issue 

cost_o £_issue = 5 
v current inventory 

current_Tnventory = 23 
v total_stock_value 

total_stock_value = (invalid decimal data) 
v octal ( total_stock_value) . 

040040040040040040040040040 -^ U* i-O^U-w/ 
v unspec ( total_stock_value) 

"0 00100 000000100 00 000010000000 010000000010000 000010000 0000 
100 00000 01000 00000100000 "b 
display total stock value a 8 



display to tal_stock_value o 2 2 ^ oP 



040040040040 040040040040 

q 

r 14:59 0.928 72 level 2 



^ 



h 
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SCENARIO III - PROGRAM MANI.PUAL-TION 



MORE TOOLS 



I THE where REQUEST 



I THIS REQUEST TELLS THE PROGRAMMER THE VALUES OF probe's TWO 
DEBUGGING POINTERS 



I USAGE: 
where 
wh 

where <pointer> 
wh <pointer> 

I EXAMPLES: 
where 
wh sc 
where control 

I NOTES: 

THE TWO POINTER SPECIFICATIONS ARE: 

source, sc 

control, ctl 

THE position AND use REQUESTS CHANGE THE VALUE OF THE SOURCE 
POINTER 



I THE use REQUEST 
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SCENARIO III - PROGRAM MANIPUALTION 



I MOVES THE SOURCE POINTER TO A NEW LOCATION 



I UNLIKE THE position REQUEST, THIS DOES NOT DISPLAY THE FINAL 
LOCATION 



I USAGE: 
use 

use <absolute line number> 
use <relative line number> 
use level <number> 
use <program name) 
use <character string> 

I EXAMPLES: 
use 

use level 5 
use 138 
use foo 
use +3 
use "vl = 5" 

I NOTES: THIS REQUEST CANNOT BE USED WITHOUT THE TABLE OPTION 

I THE call REQUEST 

I INVOKES ANOTHER PROGRAM JUST AS IF IT HAD BEEN A SUBROUTINE 
CALL 

I USAGE: 

call <program name> (<parameters>) 

Not To 3e Reproduced 4-10 F21 



... SCENARIO., .III. ...,- .PROGRAM. MAN I PU ALT! ON ... 

I EXAMPLE: 

call my_prog (argl, arg2} 

call com err_ (code, "from probe") 

I NOTES: 

probe PERFORMS VALUE CONVERSION AS PART OF THE CALL 
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SCENARIO III. - PROGRAM MANIPUALTION 



I THE NEXT EXAMPLE 



pb check_back_issues 

Using check back issues (no active frame) . 

ps get_record 
get_record: proc {); 
a: (sk;halt) 
Break set after line 153 

q 

r 15:25 0.745 236 

check_back issues 

from (specify vol:num): 1:1 

to (specify vol:num):l:4 

9 get__record (line 153) 

8 print_record (line 83) 

7 check back issues (line 65) 

6 simple_command_processorl 12265 

5 command processor_ | 11070 

4 abbrev T5336 

3 listen_| 10031 

2 process_overseer 140055 

1 user_init_admin__T42452 (aim) 

Stopped after line 153 of get_record. (level 9) 

where 

line 153 in get_record (level 9) 

Control at line~"l53 of get_record. 

use level 8 

sc 

call get_record (); 

use level 7 

where 

line 65 in check_back_issues (level 7) 

Control at line 153 of get_record. 

sc 

call print_record (); 

value issue 

issue = 1 

c 
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SCENARIO III, - , p.ROqRAMt MANIPU&LTIQN 



this 
.00. 



volume 1 number 1 

stocked: 23 outstanding requests: costi 
issue: 

9 get record (line 153) 
print_recorcT (line 88) 
check back_issues (line 65) 
simple command_processor 1 12265 
command processor 111070 
aaccev idjod 
listenj 10031 
process overseer 140055 
user inTt_admin_T42452 (aim) 
line 153 of get record, (level 



\cof 
$5 
8 
7 
6 
5 

A 

3 
2 
1 

Stopped 

v issue 

issue = 2 

v number of_issues 

number_o?_issues = 

quit 

r 17:12 1.216 128 



after 



9) 
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SCENARIO IV - PROSE VARIABLES 



a MANAGING YOUR OWN VARIABLES 

I probe ALLOWS THE PROGRAMMER TO SET UP VARIBLES KNOWN TO PROBE 
ONLY, BUT AVAILABLE FOR USE DURING ALL OF probe's PROCESSING 
(BREAKPOINTS, ETC.) 

I ALMOST LIKE HAVING A PL/I INTERPRETER 

I THE declare REQUEST 

I USAGE: 

declare <name> <type> 
del <name> <type> 

I EXAMPLES: 

del pb counter 1 fixed 

del TOTPCT real 

del sum-calc comp-6 -force 

I NOTES: 

THREE DATA TYPES ARE SUPPORTED: 

fixed, integer, int, comp-6 

float, real 

pointer, ptr 
USE THE -force CONTROL ARGUMENT TO REDEFINE A PROBE VARIABLE 



IF A probe VARIABLE IS THE SAME NAME AS A PROGRAM VARIA3LE, 
PREFIX THE orobe VARIA3LE WITH A PERCENT SIGN 
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SCENARIO IV ,t. PROBE VARIABLES 

I THE list_variables REQUEST 

I LISTS THE NAMES, DATA TYPES AND VALUES OF probe VARIABLES 

I USAGE: 

list_variables 
i — .. 

19V 

I EXAMPLES: 

list_variables 
Isv 

I ONE MORE REQUEST 

I THE If REQUEST 

I CONDITIONALLY EXECUTES A SET OF probe REQUESTS 

I USAGE: 

if <conditional> : (<request list>) 

I EXAMPLES: 

if a=b : (value a; halt) 

if varl = 4.56 : let var2 = 

I NOTES: 

CURRENT IMPLEMENTATION ALLOWS FOR ONLY SIMPLE EXPRESSION 
EVALUATION; USE THE help REQUEST TO CHECK ON NEW DEVELOPMENTS 

THE USE OF RELATIONAL OPERATORS IN THE EXPRESSION DEPENDS 
UPON THE LANGUAGE SPECIFIED TO probe 
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SCENARIO IV-.- PROBE VARIABLES 



(E.G. PL/I USES =, FORTRAN USES .eq.) 
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... Sq.EN ARXO .. IV. ,.j», , PRO BE . VARIABLES. ••. 






r 17:16 0.122 4 , 



pb check back__issues/Using check_back_issues (no active 
frame). fps get record /get_record : proc (); declare 
times__get__reco repealled f ixed/list__var iables 
times~get~record~"called fixed'O a: (let 

times_get~record~"called = times_get_record_called + l;call 
ioa__ ("get_record called * I times", / / 

time's get record called);) Break set after line 153/q/r 
17:20~0.3l0 85 " / / 

check_back issues 

Trom (specify vol:num):l:l 

to (specify vol :num) : 1:4 get record called 1 times 

volume 1 number 2 

stocked: 30 outstanding requests: 2 cost of 
this issue: 

$3.00.get__record called 2 times 

volume 1 number 3 

stocked: 27 outstanding requests: cost of 
tui s i ssue : 

$3 . O0.get_record called 3 times 

volume 1 number 4 

stocked: 20 outstanding requests: 1 cost of 
this issue: 

$3. O0.get_record called 4 times 

volume 1 number 5 

stocked: 40 outstanding requests: cost of 
this issue: 
$3.00. 

number of issues stocked: 117 

number of requests pending: 3 

total stock value: $351.00. 

r 17:21 0.660 61 
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■■-■■■■■.-■•- SCENARIO ■ IV - PROBE VARIABLES 

I THE let REQUEST 

I ASSIGNS THE VALUE OF AN EXPRESSION TO A GIVEN VARIBLE 

I USAGE: 

let variable = expression 

let cross^section = expression 

I EXAMPLES: 

let a = 5 let array (2,i) = a - 5 let substr (alpha, 2, 3' 
"abc" 
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SCENARIO IV - PROBE VARIABLES: 



r 18:08 0.156 4 

pb check back Issues Using check_back__issues (no active 
frame), ps get__record get_record: proc () ; ps "return" 
return? 

bs if current_volume=last_ > issue_volume : if 

current number=lastissue_num :call ioa__ ("just positioned 

Break set before line 175 
list_variables 

times_get_record_called fixed 4 
let times get_record_called = 

q 

r 18:11 0.386 50 

check back issues 

from TspecTfy vol:num): 1:3 

to (specify vol:num):l:6 

"' volume ' 1 ' number ' A- 

stocked: 20 outstanding requests: 1 cost of 
thi s x ssue : 

$3.00. volume 1 number 5 

stocked: 40 outstanding requests: cost of 
this issue: 

S3. 00. just positioned to last desired record 

volume 1 number 6 

stocked: 35 outstanding requests: 4 cost of 
this issue: 

$3.00. volume 2 number 1 

stocked: 30 outstanding requests: 2 cost of 
this issue: 
$3.00. 

number of issues stocked: 125 
number of requests pending: 7 
total stock value: " $375.00. 
r 18:11 0.795 24 
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SCENARIO IV - PROBE VARIABLES 



pb check_back_issues 

Using check_back_issues (no active frame). 

ps get_record 

get_record: proc {); -- ■ 

a: (let times get record_called = times — get__record__called + 1; 

v times get_record~callad) 

Break set after line 153 

q 

r 18: 13 0.245 2 



check back issues 

from TspecTfy vol:num): 1:3 

to (soecify vol :num) : 1:6 

1 

2 

3 

4 

volume 1 number ■ 4 

stocked: 20 'outstanding requests: 1 cost of .this 

issue: 
5 3 . u •j • 5 

volume 1 number 5 

stocked: 40 outstanding requests: cost of this 

issue : 

S3. 00.6 .just positioned to last desired record 

volume 1 number 6 

stocked: 35 outstanding requests: 4 cost of this 
issue : 
$3.00.7 

volume 2 number 1 

stocked: 30 outstanding requests: 2 cost of this 
issue : 
$3.00. 

number of issues stocked: 125 
number of requests pending: 7 
total 'stock value: $375.00. 
r 18:14 1.105 6 
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". Scenario iv - probe variables 



pb check back issues 

Using check back__issues {no active frame) . 

st 

Break exists after line 153 in check back issues 

Break exists before line 175 in checE_bac"Ic issues 

ps 153 

get_record: proc (); 

st at 153 

Break exists attar line 153 :let times get record called — 

times^jge^record^called + 1; v times get_record_called 

a: (let times__get_record_called = times_get_record_called + 

l;call ioa__ ("get_record called "d times"", 

times__get_record_called) ) 

3reak set after line 153 

ps 1 

check_back_issues: 
proc; 

a 
..Break. ...set .a,.f.ter, ,1 ine , :: i.,. ..,.,„. ........ ,,.;,,. 

•asle.t .times_get^r.ecord-_called = 0. 

Break' set af ter~~iine' 1 '" " '' 

q 

1 O . 1 1 A 
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Topic V MULTICS USER-RING RUNTIME STRUCTURES Topic V 



OBJECTIVES: 



Upon completion of this topic? students should be able to! 



1. Describe some of the ways in which processes can be 
inadvertently destroyed. 



segments : 

dses 
kst 
pds 

stack_1 - stack_7 (as appropriate) 
:.'.C unique .area. 1 i niter 3 

3. Describe the format of the following structures: 

linkage offset table (LOT) 
internal static offset table (ISOT) 
ref erence_narne_table (RNT) 



4. Name the sections of a standard Multics object sesment and 
give the functions of each. 
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INTRODUCTION 



a INTRODUCTION 



I THERE IS NO CENTRALIZED LOCATION FOR ALL PROGRAM SUPPORT TABLES 
AND DATA IN MULTIC3 



I NATIVE MULTICS USES SEVERAL SEGMENTS TO MANAGE RUNTIME 
INFORMATION 



I MOST ARE FOUND IN THE PROCESS DIRECTORY 

I THE PROCESS DIRECTORY IS CREATED FOR A USER AT LOGIN TIME 
I IT IS PART OF THE HIERARCHY, JUST AS THE HOME DIRECTORY IS 
I IT IS. GIVEN A SHRIEK NAME. AS ITS . IDENTITY. 

I THESE TABLES ARE MODIFIABLE BY PROGRAMS IN A PROCESS 

I THEIR MISUSE IS THE MAIN CAUSE OF PROCESS FAILURE 
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INTRODUCTION 





j 


I r 04:38 0.163 I 




! pd 

1 >process dir dir> JBXNCwXCBBBBBBB 

1 r 04:38 0.044 




I cwd [pd] 

i r 04:38 0.047 




1 list 




i Segments ■ 7, Lengths = - 




1 rew IBBBJLFKcGzxlDq. temp. 0326 




1 rew IBBBJLFKcGxPLpJ. area. linker 
1 rew stack_4 




1 re pit 




1 pds 
J.-. 0., lest,. 




1 . dseg . 




I r 04:38 0.196 
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SUPERVISOR SEGMENTS 



a dseg 



I DESCRIPTOR SEGMENT 



I RESIDES IN RING 



I USED BY THE HARDWARE TO CALCULATE MEMORY ADDRESSES 



I IS NOT ACCESSIBLE TO THE USER 



s test 



I KNOWN SEGMENT TABLE 



I RESIDES IN RING 



s IS NOT ACCESSIBLE TO THE USER 



I IS USED INDIRECTLY BY VIRTUAL MEMORY OPERATIONS 



I IS AN ARRAY OF BLOCKS, EACH BLOCK CONTAINING INFORMATION 
ABOUT EACH SEGMENT THE PROCESS IS CAPABLE OF REFERENCING 
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SUPERVISOR SEGMENTS 



I FOR A SEGMENT TO BE USED IN A PROCESS (E.G. PRINTED, EDITED, 
EXECUTED) IT MUST HAVE AN ENTRY IN THE kst 

I IF A SEGMENT HAS AN ENTRY IN THE kst IT IS CONSIDERED "KNOWN" 



a nd =; 



I PROCESS DATA SEGMENT 



I RESIDES IN RING 



I CONTAINS MANY THINGS . THE. SUPERVISOR . WANTS TO . KNOW ABOUT.. YOUR 
"■•■' ''PROCESS 5 "' 



I YOUR PROCESS ID 

I YOUR USER ID 

I PROCESSOR INFORMATION FOR FAULT AND CONDITION PROCESSING 

I RING INFORMATION 

I MORE 

I NOT ACCESSIBLE TO THE USER 
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KSTE FOR 

SEGMENT 

342 



KSTE FOR 

SEGMENT 

341 



j KSTE FOR 
SEGMENT 
34Q 



SUPERVISOR SEGMENTS 




SEG 344 



3EG 343 



SEG 342 



SEG 341 



SEG 340 



SEG 337 



S&G 336 



asea 



FAULT DATA 



FAULT DATA 



FAULT DATA 



J. 



t i ' r 



1 — r 



xrx 



DATA CELLS 



pds 
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THE STACK .SEGMENT - STACK N 



a USER STACK 

I FUNCTION 

I IS THE BACKBONE OF THE MULTICS PROGRAMMING ENVIRONMENT 






I USED TO DEFINE THE REST OF THE PROGRAMMING ENVIRONMENT 

I THE STACK IS DIVIDED INTO TWO FUNCTIONAL PARTS 

I AT THE BEGINNING OF THE STACK IS THE STACK HEADER 

t THE HEADER" CO'NTAINS- 'POINTERS OF ALL 'THE OTHER TABLES USED 



I AT SOME POINT INTO THE STACK SEGMENT (DEPENDING ON THE STACK 
ITSELF) ACTIVATION FRAMES WILL 3E FOUND 



I EACH FRAME CONTAINS INFORMATION ABOUT VARIABLES OF A 
CURRENTLY ACTIVE (CALLED, BUT NOT YET RETURNED) PROGRAM 



I THE SIZE OF THE STACK IS NOT PREDICTABLE, BECAUSE AS PROGRAMS 
ARE CALLED AND RETURN THE STACK WILL GROW AND SHRINK 
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THE STACK SEGMENT - STACK N 




POINTER TO FIRST FRAME 



NULL 
POINTER 



POINTER 
TO LINKS 



POINTER 
TO PROGRAM 



POINTER 
TO LINKS 



POINTER 
TO PROGRAM 
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THE" STACK SEGMENT - STACK N 



~-i a *-i r-t s-> r-* m m * Of T? — . ftJX? T fST 1 



THE LINKAGE, urroti TftObL - a "^ •-"-"■ 



I IS USED BY THE DYNAMIC LINKER AND BY PROGRAMS TO FIND THEIR 
LINKAGE INFORMATION 



I IS QUITE SIMPLY AN ARRAY OF ONE WORD ADDRESSES SHOWING WHERE 
VARIOUS LINKAGE SECTIONS ARE 

I TO FIND OUT WHERE THE LINKAGE INFORMATION FOR A PROGRAM (CALL 
IT foo) , FIRST OBTAIN ITS SEGMENT NUMBER 

T COUNT UP THAT MANY WORDS FROM THE BEGINNING OF THE LOT AND 
THE WORD AT WHICH YOU ARRIVE CONTAINS THE ADDRESS OF foo S 
LINKAGE INFORMATION 



X "'■"■'THE"-"'t6*-- HAS" A : N' INITIAL' SIZE 'OF 512 WORDS' 'AND ' IS ACTUALLY 
OVERLAID UPON THE BEGINNING OF THE STACK 



a THE INTERNAL STATIC OFFSET TABLE - THE ISOT 



I THE ISOT CONTAINS ONE WORD ADDRESSES OF THE STATIC SECTIONS OF 
ALL THE ACTIVE PROGRAMS 



I IT TOO IS AN ARRAY OF THESE ADDRESSES 



I TO FIND THE LOCATION OF SOME PROGRAM'S STATIC SECTION, ONE 
rntlNTS UP ITS SEGMENT NUMBER WORTH OF WORDS AS IN THE LOT 
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THE STACK SEGMENT - STACK N 



I THE SIZE OF THE ISOT IS ALSO 512 WORDS LONG AND IT IS FOUND 
RIGHT AFTER THE LOT ON THE STACK 



I BECAUSE OF THE LOT AND ISOT, THE FIRST STACK FRAME USUALLY 
BEGINS RIGHT AFTER THE ISOT 
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THE STACK' SEGMENT - -STACK N 




Not To Be Reproduced 



5-10 



F21 



THE AREA. LINKER SEGMENT 



a THE COMBINED LINKAGE AREA 



I AS WILL BE SEEN IN DYNAMIC LINKING, SOME INFORMATION FROM AN 
OBJECT SEGMENT NEEDS TO BE COPIED OUT INTO A WRITSA3LE AREA 



I THE COMBINED LINKAGE AREA IS ONE OF THE TWO AREAS THAT HOLD THIS 
COPIED DATA 



I THE COMBINED LINKAGE AREA IS A PL/I TYPE AREA - A MANAGED POOL 
OF STORAGE FOR ALLOCATING AND FREEING DATA 



I HISTORICALLY THE COMBINED LINKAGE AREA WAS A PHYSICALLY SEPARATE 
AREA APART FROM OTHER RUNTIME AREAS. 



I NOW IT IS JUST A "SYNONYM" FOR THE area. linker 



T Tit3C»ri c^no it muff wunr c **»^-» 1 i^l**5.v nn\i ott TUnnriUT 1 H7 AQ TWU 



COMBINED LINKAGE AREA 



s THE COMBINED STATIC AREA 



I MODIFIABLE STATIC DATA IS MAPPED OUT IN THE OBJECT SEGMENT WHEN 
IT IS CREATED, BUT NEEDS TO BE MODIFIED 



I TO PREVENT THE MODIFICATION OF THE OBJECT ITSELF, THE STATIC 

DATA TEMPLATE IS COPIED FROM THE OBJECT TO THE COMBINED STATIC 

SECTION (COMBINED BECAUSE IT IS COMBINED WITH THE STATIC 
SECTIONS OF OTHER PROGRAMS) 
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THE AREA. LINKER SEGMENT 




FREE 
BLOCKS 



ADDR 



ADDR 



ADDR 



ADDR ADDR 



t 

ADDR J ADDR 



ADDR 



ADDR j ADDR ADDR 



ADDR 



ADDR 



ADDR 



ADDR j ADDR ADDR 



SIZE 



HWM FIRST 



LG.BK. 



VERSION 
TWO 
AREA 
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THE AREA. LINKER SEGMENT 



I THE COMBINED STATIC AREA IS AGAIN A PL/I TYPE AREA 



I THE COMBINED STATIC AREA IS ANOTHER SYNONYM FOR THE area. linker 
SEGMENT 



a THE REFERENCE NAME TABLE - THE RNT 



I THE REPOSITORY FOR A SET OF ATTRIBUTES CALLED REFERENCE NAMES 

I A REFERENCE NAME IS AN ATTRIBUTE OF A SEGMENT FOR PROGRAMMING 
PURPOSES 



I A' REFERENCE "NAME EXISTS ONLY. WITHIN A PROCESS - IT IS NOT 
PERMANENT" 



I IT IS A SYNONYM FOR A SEGMENT THAT IS THE OBJECT OF A SEARCH 



I IT MAY OR MAY NOT BE RELATED TO THE ACTUAL NAME OF THE 
SEGMENT 



I IT. IS CREATED IMPLICITLY OR EXPLICITLY 

■ I WHEN A PROGRAM IS CALLED IT IS' GIVEN A REFERENCE NAME 

I WHEN THE RING initiate PROGRAM IS CALLED (THROUGH A 
GATE, OF COURSE) 



I THE RNT ALSO MAINTAINS THE ASSOCIATION BETWEEN A REFERENCE NAME 
AND THE SEGMENT NUMBER OF A SEGMENT 
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THE , AREA ..LINKER, .SEGMENT 



I THE RNT IS IN THE FORM OF A RATHER INVOLVED SERIES OF LINKED 
LISTS 



I THE RNT IS DEFINED BY A HEADER WHICH CONTAINS TWO HASH 
TABLES, ONE FOR SEGMENT NUMBERS AND ONE FOR REFERENCE NAMES 

I EACH ENTRY IN THE RNT IS IN TWO LINKED LISTS - A REFERENCE 
NAME LIST AND A SEGMENT NUMBER LIST 



I THE RNT RESIDES IN THE MIDDLE PORTION OF THE area. linker SEGMENT 



I IT MANAGES ITS OWN AREA IN THIS SEGMENT 



a THE USER' FREE'AREA 



I USED FOR ALLOCATING CONTROLLED A:iD SOME BASED VARIABLES, FOR 
FORTRAN COMMON AND FOR COBOL DATA 



I OBVIOUSLY, BY NOW, IT IS A PL/I AREA 



I THE USER FREE AREA ALSO IS A "SYNONYM" FOR THE area. linker 
SEGMENT 



I TO RUN A PROGRAM THE USER MUST 

I CREATE AN OBJECT SEGMENT ACCEPTABLE TO THE MULTICS LINKERS 
I CALL THE PROGRAM 
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THE AREA. LINKER SEGMENT 



COMBINED STATIC AREA 



INTERNAL 
STATIC 
SECTION 



ISOT 



P 






LOT 



LINKAGE 
SECTION 



jm 



r\ 



sbol control daca 



axe 



prog 



C # 



E * 



? # 



DIRECTORY 



STACK 



SYSTEM FREE AREA 
(gec_sys cea_£ree_arsa__) 



REGISTERS 
CALLING HISTORY 



AUTOMATIC 



STACK *- 
HEADER •- 



—• • 



BASED DATA- 
IM AN AREA 



ASSIGNED LINKAGE AREA 
(hc3_Sassign_ltnkage) 











5A5SD DATA- 
IN AN AREA 











CO SOL 

RUN UNIT 
INFO 



exc •■ 
prog • 
prog.pU • 



PATHNAMES 



p 


I 
N 

T 
E 
R 
S 



EXT. STATIC & 
COMMON BLOCKS - 
PER PROCESS 



EXTERNAL 

"*DATA 

CONTROL 
f INFO 



CONTROLLED 
INTERNAL 



T 



CONTROLLED 
EXTERNAL 



•"-♦To 



OSOL PROGRAM 
DATA 



BASED DATA- 
NO AREA 



3ASED DATA- 
IN I/O 3UFFER 



SOURCE 
PROGRAM 



OBJECT 
PROGRAM 



EXTERNAL STATIC 
AND COMMON 3LOCKS- 
PERMANENT 



exc 



prog 



prog.pU 



U 
S 

E 
K: 

F 

R 
E 

A 
R 

£ 
A 
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.THE AREA ..LINKER SEG.MENT 

I FROM ANOTHER PROGRAM 

call prog$entry () ; 
I OR, BY INVOKING IT AT COMMAND LEVEL 

prog$entry 

I THE COMMAND LEVEL INVOCATION DOES NOT CALL IN THE DYNAMIC 
LINKER, WHILE THE CALL STAEMENT MAY 

I THE OBJECT SEGMENT FUNCTIONS TO 

I PROVIDE INSTRUCTIONS AND DATA IN THE MACHINE'S LANGUAGE 

I INSTRUCTIONS ARE CURRENTLY IN L68 MACHINE CODE 

I THE DATA IS PROVIDED FOR THE MULTICS LINKER, PRELINKER, 
BINDER, AND DEBUGGERS 

I 'COMPOSED -OF T SECTIONS 

I TEXT SECTION 

I DEFINITION SECTION 

I LINKAGE SECTION TEMPLATE 

I STATIC SECTION TEMPLATE (OPTIONAL) 

I SYMBOL SECTION 

I OBJECT MAP 

I OBJECT MAP POINTER 
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I TEXT SECTION 

I PURE PART OF AN OBJECT PROGRAM 

I CONTAINS: 

I INSTRUCTIONS (NO SELF-MODIFYING INSTRUCTIONS) 
I ENTRY SEQUENCES 
1 READ-ONLY DATA 

I ' DEFINITION SECTION 

I NONEXECUTABLE, READ-ONLY SYMBOLIC INFORMATION 
I USED FOR DYNAMIC LINKING 
I . USED FOR SYMBOLIC DEBUGGING '. 

I CONTAINS 

I DEFINITIONS 

I OFFSETS OF NAMED ENTITIES IN TEXT AND OTHER SECTIONS 

I DEFINITION HASH TABLE (OPTIONAL) TO EXPEDITE THE LINKER'S 
SEARCHES 

I SYMBOLIC NAMES OF EXTERNAL REFERENCES 
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THE -ftBEASHJJKER. SEGMENT 



I LINKAGE SECTION TEMPLATE 

I INITIAL CONTENTS OF THE IMPURE, NONEXECUTABLE PART OF A 
PROGRAM 

I USED FOR DYNAMIC LINKING 

I CONTAINS 

I UNSNAPPED LINKS TO EXTERNAL REFERENCES 

I DATA ALLOCATED ONCE PER-PROCESS (INTERNAL STATIC DATA) 

I COPIED INTO COMBINED LINKAGE AREA IN THE PROCESS DIR WHEN 
OBJECT SEGMENT IS FIRST REFERENCED 
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THE AREA. LINKER SEGMENT 



I STATIC SECTION TEMPLATE 



I THE INITIAL CONTENTS OF IMPURE, NONEXECUTABLE DATA FOR OBJECT 
PROGRAM 



I DATA IS 

I ALLOCATED ONLY ONCE PER PROCESS 
I INITIALIZED ONLY ONCE PER PROCESS 



I USUALLY INCLUDED AS PART OF LINKAGE SECTION UNLESS THE 
-separate_static CONTROL ARGUMENT IS USED WHEN COMPILING THE 
PROGRAM 



I COPIED INTO COMBINED STATIC AREA IN PROCESS DIR WHEN OBJECT 
SEGMENT IS FIRST REFERENCED 
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THE AREA .LINKER SEGMENT 



I SYMBOL SECTION 

I IS PURE 

I CONTAINS INFORMATION NOT BELONGING IN OTHER SECTIONS 

I USED FOR SYMBOLIC DEBUGGING 

I USED FOR OBJECT PROGRAM STATUS COMMANDS (SUCH AS pli) 

I INFORMATION DOCUMENTING CREATION OF OBJECT PROGRAM 

I RELOCATION INFORMATION 

I SOURCE SYMBOL NAMES AND STORAGE LOCATIONS (PRESENT ONLY IF 
-table OPTION SPECIFIED) 

I NOTE: IN THE CASE OF BOUND OBJECT, THIS SECTION MIGHT BE 
FURTHER STRUCTURED INTO A THREADED LIST OF VARIABLE LENGTH 
"• " SYMBOL 3L0CKS 
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THE AREA. LINKER SEGMENT 

I OBJECT MAP 

I DEFINES THE LOCATION (OFFSET) AND LENGTH OF OTHER SECTIONS 

I DEFINES OBJECT SEGMENT FORMAT 

I SINGLE (UNBOUND) OBJECT PROGRAM, OR 

I SEVERAL OBJECT PROGRAMS, BOUND TOGETHER 

I OBJECT MAP POINTER 



I AN 18-BIT OFFSET IN THE UPPER HALF WORD OF THE LAST WORD IN 
THE OBJECT SEGMENT 



I GIVES ' LOCATION OF OBJECT MAP, RELATIVE TO BASE OF OBJECT 
SEGMENT 



I FOUND USING THE 3IT COUNT 
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THE AREA. LINKER- SEGMENT 




0kl«tT 
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THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



a CONSTANTS 



I CONSTANT DATA VALUES, KNOWN ONLY TO ONE PROGRAM 



I DECLARATION 



I PL/1: del con fixed bin internal static options( constant) 

initial (3) ; 



I COBOL: CONSTANT SECTION. 

77 CON; PIC IS 99; VALUE IS 3, 



I FORTRAN: parameter con=3 

T r r\n * mr r\\i 

T TM TMC TTVT" CCrTTHM HP TUf DDfir!9JM 

I ALLOCATED AND INITIALIZED 

I ONCE BY THE COMPILER, WHEN THE SOURCE PROGRAM IS COMPILED 

I FREED 

I NEVER 
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THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



a INTERNAL STATIC 



I PER PROCESS DATA, KNOWN ONLY TO ONE PROGRAM 



1 UCCL.AKA1J.U1N 



I PL/1: declare is internal static; 
I FORTRAN: save is 

I LOCATION 

I IN .INTERNAL. STATIC SECTION OF PROGRAM,- WHICH. IS THEN COPIED 
: TO [unique] .area. linker 

I NOTE: SUCH VARIABLES CAUSE THE SIZE OF THE OBJECT TO GROW 

I ALLOCATED AND INITIALIZED 

I FIRST TIME OBJECT SEGMENT IS CALLED IN THE PROCESS BY COPYING 
OBJECT'S LINKAGE SECTION (OR SEPARATE STATIC SECTION) 



I FREED 



I WHEN PROCESS TERMINATES, OR WHEN OBJECT SEGMENT IS EXPLICITLY 
TERMINATED {terminate COMMAND) 
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" THE AREA. LINKER SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 

a AUTOMATIC 

I PER PROGRAM-ACTIVATION DATA, KNOWN ONLY TO ONE PROGRAM 

I DECLARATION 

I PL/1: declare a automatic; 
I FORTRAN: automatic a 

I LOCATION 

I "ALLOCATED" -IN STACK FRAME WHEN FRAME IS PUSHED 

I ALLOCATED AND INITIALIZED 

I EACH TIME PROGRAM IS CALLED 

I FREED 

I WHEN PROGRAM RETURNS 
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THE AREA-; LINKER' SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



a EXTERNAL STATIC - PER PROCESS 



I PER PROCESS DATA, SHARED BETWEEN PROGRAMS, STORED IN TEMPORARY 
SEGMENTS IN THE PROCESS DIRECTORY 



I DECLARATION 

I PL/1: declare e external static; 



I FORTRAN: common b,c 

common /e/b,c 



I ' LOCATION 

I ALLOCATED IN USER FREE AREA 

I ALLOCATED AND INITIALIZED 
I WHEN FIRST REFERENCED 

I FREED 



I WHEN PROCESS TERMINATES, OR EXPLICITLY (SEE 
reset_external_var iables AND delete external variables 
COMMANDS ) ~* 
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THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



a EXTERNAL STATIC - PERMANENT 



I PERMANENT DATA, SHARED BETWEEN PROGRAMS, STORED IN USER-SUPPLIED 
SEGMENTS 



I DECLARATION 



I PL/1: declare ext$ external static, 

ext$e external static; 



I FORTRAN: common /ext$/b,c 
common /ext$e/b,c 



I LOCATION .- .• •■■.•.." 

I IN PERMANENT SEGMENT ext, FOUND BY LINKER (USING OBJECT 
SEARCH RULES) 



I SEGMENT MUST EXIST PRIOR TO EXECUTION 

I ALLOCATED AND INITIALIZED 

I WHEN SEGMENT ext IS CREATED 

I FREED 

I EXPLICITLY BY DELETING THE CONTAINING SEGMENT 
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. THE AREA. LINKER SEGMENT ' 
GE'TTING SPACE FOR PROGRAM VARIABLE: 



CONTROLLED STORAGE - INTERNAL 



I EXPLICITLY-ALLOCATED DATA, KNOWN TO ONE PROGRAM 



1 UEil-ijrtrift i iULN 



I PL/1: del c controlled int; /* int is default */ 
allocate c; 
allocate c; 



I LOCATION 

I ALLOCATED IN* USER FREE 'AREA IN [unique] . area .linker 

I ALLOCATED AND INITIALIZED 

I EXPLICITLY 3Y PL/1 allocate STATEMENT 

I FREED 

I EXPLICITLY 3Y PL/1 free STATEMENT ' 
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THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



s CONTROLLED STORAGE - EXTERNAL 



I EXPLICITLY-ALLOCATED DATA, SHARED BETWEEN PROGRAMS 



I DECLARATION 



I PL/1: declare ce controlled external; 
allocate ce; 



I LOCATION 

I ALLOCATED IN USER FREE AREA IN [unique] .area . 1 inker 

I ALLOCATED AND INITIALIZED 



I EXPLICITLY BY PL/I allocate STATEMENT 



I FREED 

I EXPLICITLY BY PL/1 free STATEMENT 
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, THE AREA..LINKER SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 



9 BASED - IN AN AREA 



I EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIEI 
BY A LOCATOR 



I DECLARATION 



I PL/1: del area area, 

b based (p) , 
P Ptr ; 
allocate b in (area); 



I LOCATION 

I "DEPENDS WHERE THE USER SPECIFIES THE AREA TO BE (PERHAPS THE 
SYSTEM FREE AREA SUPPLIED 3Y INVOKING get system free area ) 



I ALLOCATED AND INITIALIZED 

I EXPLICITLY BY PL/1 allocate STATEMENT 

I FREED 

I EXPLICITLY 3Y PL/1 free STATEMENT 
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THE AREA, LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



a BASED - NO AREA 



I EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIED 
BY A POINTER 



I DECLARATION 



I PL/1: declare b based(p) , 

(P/pl) ptr; 
allocate b; 
allocate b set(pl); 



I LOCATION 

I IN USER FREE AREA WITHIN [unique] .area. linker 



I ALLOCATED AND INITIALIZED 



I EXPLICITLY BY PL/1 allocate STATEMENT 

I FREED 

I EXPLICITLY 3Y PL/1 free STATEMENT 
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THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



BASED - IN AN I/O BUFFER 



I EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIED 
BY A POINTER 



I DECLARATION 



I PL/1: declare b based(p) , f file; 
read file(f) set(p) ; 
locate b file(f) set(p); 



I LOCATION 



I I.N. -AN" I/O BUFFER. .ALLOCATED BY. , PL/1 IN ..USER FREE AREA. .I.N 
[unique']-. area .1 inker • 



I ALLOCATED 

I EXPLICITLY 3Y PL/1 read (WITH set OPTION) OR locate STATEMENT 

I INITIALIZED 

I BY locate STATEMENT 

I FREED 

I 3Y SUBSEQUENT I/O OPERATION ON THE FILE 
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THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



a COBOL DATA 



I INTERNAL STATIC-LIKE DATA, KNOWN ONLY TO ONE PROGRAM 



I DECLARE 



I COBOL: WORKING SECTION, 
77 CB PIC IS 99, 



I LOCATION 

I ALLOCATED IN USER FREE AREA 

I ALLOCATED AND INITIALIZED 

I WHEN THE PROGRAM IS FIRST CALLED 

I FREED 



I WHEN THE PROCESS OR COBOL RUN UNIT TERMINATES, OR EXPLICITLY 
(BY A cancel cobol program COMMAND OR A CANCEL STATEMENT) 
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Topic VI MULTICS DYNAMIC UNKING Topic VI 

OBJECTIVES: 

Upon completion of this topic? students should be able to! 

1. Compare conventional linking with Multics dynamic linking. 

2. List the functions performed by the Multics dynamic linker 



3. Trace the operation of the dynamic linker from the time it 
first encounters an unsnapped link until it resolved the 
linkage fault. 



4. Discuss the side-effects of dynamic linking and some of the 
dangers related to it. 



5. EKPlain what happens when binding occurs and why it can be 
used to. great, advantage.. 
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INTRODUCTION 



a LINKING 



I A LINKER IS BASICALLY A POST COMPILER 



I SYMBOLIC REFERENCES TO LOCATIONS NOT WITHIN THE OBJECT NORMALLY 
CAUSE THE TRANSLATOR TO PRINT AN ERROR MESSAGE 



I TELLING THE COMPILER OR ASSEMBLER THAT A SYMBOL IS EXTERNAL IS 
JUST A FUDGE SO THAT IT WON'T COMPLAIN 



I THE TRANSLATOR STILL CAN'T CALCULATE AN ADDRESS, SO IT BUILDS A 
STRUCTURE TELLING WHAT IT WAS LOOKING FOR 



I- ".'IT -IS"' "THE JOB- 'Of -■•' THE LINKER ' V TO v RESOLVE kLV" THES'2 UNLINKED 

REFERENCES • • ' • ■■..■• 
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INTRODUCTION 
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INTRODUCTION 

a THE TRADITIONAL LINKER 

I PHILOSOPHY 

I LINKING MUST BE DONE BEFORE THE PROGRAM RUNS 



I LINKING IS ASSOCIATED WITH LOADING - PLACING THE PROGRAM IN 
MEMORY 



I ALL EXTERNAL REFERENCES MUST BE PRESENT AT LINKING TIME 



I THE LINKER PRODUCES A "LOAD UNIT" OR "BOUND UNIT" - ABLE TO 
BE PLACED IN MAIN MEMORY WITH ALL ADDRESSES RESOLVED 



I THE LOAD UNIT IS THEN RUN 3Y THE USER 



I LIMITATIONS 



I THE LINKER IS THE LAST STEP IN ADDRESS RESOLUTION - IF IT 
CAN'T DO IT, NOTHING CAN 



I BECAUSE TRADITIONAL LINKING IS ASSOCIATED WITH REAL MEMORY, 
ALL PROGRAMS HAVE TO BE PRESENT TO GET A SPOT IN THE BOUND 
UNIT, AND HENCE THE MEMORY 



I IF THE LINKER CAN'T RESOLVE A LINK, THE LINKING FAILS 

I CHANGING ONE PROGRAM IMPLIES LINKING EVERYTHING OVER AGAIN 

I SUBSTITUTING A PROGRAM MID-EXECUTION IS IMPOSSIBLE 



Not To Be Reproduced 6-3 F21 



INTRODUCTION 



PRE -LINKER 



?2: 



CALL [?3 J 



P.1 
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INTRODUCTION 



B THE DYNAMIC LINKER 



I PHILOSOPHY 



I IN AN OPERATING SYSTEM WITH MANY (100 PLUS) SEGMENTS, LOADING 
AND RELOCATION BECOME PART OF THE JOB OF THE HARDWARE, NOT 
THE SOFTWARE 



I RESOLVING REFERENCES BECOMES EASIER BECAUSE THE TRANSLATOR 
GENERATES ADDRESSES RELATIVE TO THE BASE OF THE PROGRAM, AND 
HENCE THE SEGMENT 



I THE JOB OF THE LINKER HAS BEEN REDUCED TO FINDING A SEGMENT 
NUMBER AND AN OFFSET WITHIN THE SEGMENT TO COMPLETE THE 
EXTERNAL REFERENCE 



'I "WT'TH" •RELOCATION' ALREADY' TAKEN CARE' OF ,' AND 'LINKING' REDUCED TO' 
THE 'CALCULATION OF TWO' NUMBERS, LINKING CAN BE POSTPONED 
UNTIL THE EXTERNAL REFEENCE IS MADE 



I ALTHOUGH DYNAMIC LINKING IS POSSIBLE USING A REAL MEMORY, 
UNSEGMENTED MACHINE, THE BY-PRODUCTS OF SEGMENTATION MAKE IT 
WORTH WHILE TO IMPLEMENT 



I WITH THE DRUDGERY OF PRE-LINKING TAKEN AWAY FROM THE 
PROGRAMMER, S/HE CAN SPEND MORE TIME WORRYING ABOUT THE 
PROGRAM, AND NOT ABOUT THE MEMORY MANAGEMENT 



I LIMITATIONS 



I EXCESSIVE USE OF DYNAMIC LINKING CAN SLOW THE OVERALL SYSTEM 
THROUGHPUT 



I BY GIVING THE JOB OF LINKING TO THE OPERATING SYSTEM, THE 
PROGRAMMER HAS LESS SAY OVER WHICH VERSION OF A PROGRAM IS TO 
BE USED 



Not To Be Reproduced 6-5 F21 



INTRODUCTION 



I ADVANTAGES 



I PROGRAMS ARE EXECUTEABLE WITHOUT ALL EXTERNAL REFERENCES 
BEING PRESENT - ONE NEED ONLY WRITE AND DEBUG A SMALL PORTION 
AT A TIME 



SUBSTITUTING SUBROUTINES CAN 3E DONE AT RUNTIME WITH LITTLE 
EFFORT AND COST TO THE OPERATING SYSTEM 



I EXTERNAL REFERENCES THAT ARE AVOIDED BECAUSE OF TRANSFERS 
WITHIN A PROGRAM NEVER HAVE TO BE RESOLVED 



Not To Be Reproduced 6-6 F21 



INTRODUCTION 




DYNAMIC LINKER 
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MULTICS COMPILER CONVENTIONS 



a EXTERNAL REFERENCES 



I ALL STANDARD MULTICS COMPILERS GENERATE THE SAME TYPE OF LINK 
THAT RELATES TO BOTH PRELINKING (BINDING) AND DYNAMIC LINKING 



I IS A REPOSITORY FOR THE EXTERNAL ADDRESS 



I CONTAINS INFORMATION TELLING ABOUT THE NAME OF THE EXTERNAL 
REFERENCE, INTERNAL LOCATIONS, WHETHER OR NOT TO CREATE IT IF 
NOT FOUND, ETC. 



a THE LINK 



I INITIALLY CREATED IN THE LINKAGE SECTION OF THE OBJECT SEGMENT 



I ONE FOR EACH EXTERNAL REFERENCE 



I IS TWO WORDS LONG 

I MAY BE UNSNAPPED 

I THE END OF THE FIRST WORD CONTAINS THE " FAULT -TRAP 2" CODE 

I THE REST OF THE LINK CONTAINS ADDRESSES OF INFORMATION FOR 
THE LINKERS 

I MAY BE SNAPPED 

I THE END OF THE FIRST WORD CONTAINS THE "ITS" CODE - 
INDICATES A VALID MULTICS POINTER 



Not To Be Reproduced 6-8 F21 



MULTICS COMPILER CONVENTIONS 



I THE FIRST HALF OF THE FIRST WORD CONTAINS THE SEGMENT 
NUMBER OF THE EXTERNAL REFERENCE 

I THE FIRST HALF OF THE SECOND WORD CONTAINS THE OFFSET 
WITHIN THE SEGMENT OF THE EXTERNAL REFERENCE 



a THF. r.TMfCArtE SFfTTnN 



I CONTAINS ALL THE LINKS A PROGRAM NEEDS 



I IS COPIED OUT OF THE OBJECT SEGMENT BEFORE THE OBJECT IS 
EXECUTED 



I IS MERGED INTO THE COMBINED LINKAGE- AREA 
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MULTICS COMPILER CONVENTIONS 



000000 I DEFS 



TRAP 



POINTER TO SYMBOL SECTION 



POINTER TO LINKS' ORIGIN 



UNUSED 



LENGTH SEGNO 



Length 



LINK 



LINK 
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MUTLICS ..OPERATING : SYSTEM SUPPORT . 



a MANAGEMENT OF EXTERNAL REFERENCES 



I WITH FEW EXCEPTIONS, COMPUTERS EXPECT ADDRESSES TO BE IN NUMERIC 
(BINARY) FORM 



I THE MULTICS HARDWARE CURRENTLY FOLLOWS THIS ARCHITECTURE 



I THE DESIGNERS OF MULTICS DECIDED THAT IT WAS TIME TO MOVE AWAY 
FROM SOFTWARE ALSO USING NUMBERS 



I PROGRAMMERS STOPPED PROGRAMMING IN BINARY MACHINE LANGUAGE 
YEARS AGO, USING A MNEMONIC ASSEMBLY LANGUAGE 

I . HUMANS REMEMBER AND MANIPULATE WORDS MORE EFFICIENTLY, .T.HAN 
s -'* a ' 4 "WMB ; ERS ;Vr 



I THE HARDWARE LOCATIONS OF DATA MAY CHANGE, BUT THE NAME WILL 
REMAIN THE SAME 



I SOFTWARE TECHNOLOGY NOW ALLOWS SYMBOLIC NAMES TO BE 
AUTOMATICALLY MANAGED CHEAPLY 



I MULTICS SUPPORTS SYMBOLIC (VIRTUAL) ADDRESSES FOR POTENTIALLY 
ALL THE DATA ON THE SYSTEM 



I SPECIFIED BY A TWO COMPONENT NAME IN THE FORM OF 
alpha$beta 

I alpha IDENTIFIES A SEGMENT 
I beta IDENTIFIES A LOCATION WITHIN THE SEGMENT 
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MUTLICS OPERATING SYSTEM SUPPORT 



I MULTICS WORRIES ABOUT THE HARDWARE NUMBER ASSOCIATED WITH 
alpha 



I MULTICS WORRIES ABOUT THE HARDWARE NUMBER ASSOCIATED WITH 
beta 



I THE PROGRAMMER IS CONCERNED ONLY WITH REMEMBERING AND 
MANAGING THE ENTITY alpha$beta 

I THIS SCHEME IS IMPLEMENTED EVEN AT THE MULTICS ASSEMBLY 
LANGUAGE LEVEL 



I MULTICS MANAGES SEVERAL TABLES TO MAINTAIN THE ASSOCIATION 
BETWEEN A SYMBOLIC NAME AND ITS HARDWARE NUMBERS 

I , dseg.., 

I kst 

I RNT 

I DEFINITION SECTION IN OBJECT SEGMENTS 

I THERE IS AN INTERPLAY AMONG THE TABLES 

I dseg AND kst CAN BE CONSIDERED AS A NECESSARY PAIR 
I dseg TELLS THE HARDWARE WHERE SEGMENTS ARE 
I kst TELLS THE SOFTWARE WHO SEGMENTS ARE 
I THE RNT LISTS ALIASES FOR SEGMENTS LISTED IN THE kst 
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THE LINKER.- PHASE I 



w TV? catir .t 



I PROLOGUE 



I THE INSTANT A PROGRAM BEGINS TO RUN, IT HAS NOT YET MADE ANY 
CALLS 

I ITS LINKAGE SECTION WILL CONTAIN ONLY UNSNAPPED LINKS BECAUSE 
LINKS ARE NOT SNAPPED UNTIL NEEDED 

I AN ATTEMPT TO REFERENCE THROUGH ANY OF THESE LINKS WILL CAUSE 
A HARDWARE FAULT 
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THE LINKER - PHASE I 



PRO 

PR1 

PR2 
PR3 

PR4 

PR5 

PR6 
PR7 



270 


7030 


110 


322 


244 


4420 


...... • .• 12] - ■■ 





260 


13200 


77 


3736 


244 


4420 


244 






000000 


DEFS 


TRAP 


POINTER TO SYMBOL SECTION 


POINTER TO LINKS' ORIGIN 


UNUSED 




LENGTH 


SEGNO JLENGTH 


LINK 


LINK 

l 
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THE LINKER -. 'PHASE T 



I THE FAULT HANDLER 



I A REFERENCE THROUGH A LINK IS DONE WITH HARDWARE INDIRECTION 

I ALL THE LINK DOES IS TELL THE HARDWARE WHERE TO GO FOR THE 
NEXT REFERENCE 

I USES AN ITS-PAIR 






l/t 



I IF THE HARDWARE FINDS THE BIT PATTERN 100110 AT THE END OF 
THE FIRST WORD OF A LINK, IT FALLS INTO A FAULT TRAP 2. 



I THE WHOLE PROCESSING UNIT IS HALTED AND THE MACHINE IS FORCED 
. TO EXECUTE THE PROGRAM fim ^^ x ^«„pt y*oA«W 

I FROM THIS POINT ON, CONTROL IS IN THE HANDS OF THE 
.... . SUPERVISOR 

I THIS IS RING ZERO ' 

I THERE IS NO WAY FOR THE USER TO INTERCEPT THIS FAULT 

I fim ASCERTAINS THAT THE FAULT WAS FAULT TRAP 2 AND CALLS THE 
PROGRAM link_snap__ 

I link_snap_ IS THE DYNAMIC LINKER 
I - ink_snap FIRST VERIFYS THAT THIS IS A VALID UNSNAPPED LINK 
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THE. LINKER - PHASE 'I 



PR4 



:60 



13200 



260 13212 



+ 



12 



OFFSET IN 
LINKAGE SECTION 





46 


ADUR2 



THE LINK 
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THE LINKER - PHASE.' I 



B SEARCH FOR THE NAME 



I link__snap LOOKS AT THE LINK THAT CAUSED THE FAULT AND EXTRACTS 
FROM IT POINTERS BACK TO THE OBJECT SEGMENT 



I IN THE OBJECT, AS PART OF THE DEFINITION SECTION, ARE 
" riMTiwft on—nccr'-D it-mi" tmi*!_c 

WITHIN IT THAT WE WANT 



»nii'Tii.!»on_npi?c | Di:Mr , TM^_cvMnnr c» that' mimc t<uv cpnMCMT i\tn rnriTTnu 

WW X fini\U E\Lli' DlVbllV J.41V U inLTUUU ± 144~l A L1£~llJU A 14kl ^yWl'IW4li l^iw MW>**i-fc.WW*i 



I link_snap OBTAINS THE TWO SYMBOLIC NAMES THAT MAKE UP THE 
VIRTUAL ENTRY DESCRIBING THE FAULTED LINK FROM THIS LIST OF 
SYMBOLS 
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THE LINKER - PHASE I 



DEFINITIONS 



LINKAGE 



SYMBOLS 



MAP 




FAULTED LINK 
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THE- LINKER - PHASE II 



a OBTAINING THE SEGMENT NUMBER 



I A SEGMENT NUMBER DESCRIBES TO HARDWARE THE LOCATION OF A REAL 
SEGMENT; THE DYNAMIC LINKER HAS TO FIND THAT REAL SEGMENT 



I THE SEARCH RULES 



I EACH PROCESS HAS A LIST OF PLACES TO SEARCH JUST IN CASE 
LINKAGE FAULTS OCCUR {WHICH IS INEVITABLE) 



I THIS IS THE USER MODIFIABLE ATTRIBUTE OF A PROCESS CALLED 
"THE SEARCH RULES" 



A SPECIAL CASE: initiated segments 

I "THE LINKER : GOES' TO-'THE'-RNT - ' 

I IT • LOOKS' UP 'THE NAME OF- 'THE SEGMENT - IT OBTAINED DURING 
PHASE I (THE RNT IS A BUNCH OF LINKED LISTS) 

I IF THE NAME IS FOUND, THEN THE NUMBER ASSOCIATED WITH IT 
IS ASSUMED TO BE THE DESIRED SEGMENT NUMBER 

I IF THE NAME WAS NOT FOUND, THEN WE MOVE ON TO THE NEXT 
SEARCH RULE 
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THS LINKER - PHASE II 
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THE LINKER - PHASE II 






I THE SECOND RULE IN THE SEARCH RULES IS ref erenc ing__dir 

I THIS MEANS THE LINKER WILL LOOK IN THE DIRECTORY OF THE 
PROGRAM THAT CAUSED THE LINKAGE FAULT FOR THE SEGMENT 

I ALTHOUGH THIS IS NOTHING MORE THAN THE LIST COMMAND, IT IS 
NOT AN INEXPENSIVE OPERATION 

I ITS PURPOSE IS TO CONTAIN THE GLOBAL NATURE OF THE DYNAMIC 
LINKER IN ITS SEARCH FOR THE SEGMENT 

I THIS TENDS TO ISOLATE ALL THE PROGRAMS IN A DIRECTORY INTO 
A SUBSYSTEM 

I THE DANGER OF THIS WILL BE STATED LATER 
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THE LINKER - PHASE II 
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THE LINKER - PHASE II 



I THE LINKER FIGURES THAT THE USER HAS THE PROGRAM AND WILL 
LIST THE CONTENTS OF THE WORKING DIRECTORY 

I THIS ALSO TENDS TO CONTAIN THE WORKING DIRECTORY INTO A 
SUBSYSTEM OF SORTS 

I IT ALSO LETS THE USER ACCUMULATE A LIBRARY OF INTERWOVEN 
PROGRAMS 
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THE LINKER - PHASE II 
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THE LINKER .-..PHASE II,, 



I SYSTEM LIBRARIES 

I HERE BEGINS THE BIG SEARCH 

I AGAIN, A LIST FOR EACH DIRECTORY UNTIL THE LINKER FINDS 
THE SEGMENT IN QUESTION 

I THIS CAN EASILY BECOME THE MOST TIME CONSUMING JOB OF THE 
DYNAMIC LINKER 



I IF THE SEGMENT WAS NOT FOUND IN EITHER THE RNT OR THE 
DIRECTORIES, THEN THE "linkage error" CONDITION IS SIGNALLED 



I IF THE SEGMENT WAS NOT FOUND ' IN THE RNT, BUT WAS FOUND IN A 
DIRECTORY, ADD IT TO THE kst AND RNT 

,.. I-;.. IF. NOT. .. «IN .THE kst T „ ; TE£N THE PROGRAM- -IS. NOT- IN- .THE . ADDRESS. *., 
"■ SPACE OF THE PROCESS AND CAN'T BE USED " 



I AFTER ADDING THE PROGRAM INTO THE kst "THE LINKER ALSO PLACES 
THE SEGMENT NAME INTO THE RNT 



I THE SEGMENT NAME WE OBTAINED IN PHASE ONE IS NOW A REFERENCE 
NAME 



I SUBSEQUENT SEARCHES FOR THIS NAME BY FUTURE PROGRAMS IS THIS 
PROCESS WILL FIND A MATCH IN THE RNT, AND HAVE AN INEXPENSIVE 
LINKAGE FAULT 
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THE LINKER - PHASE II 
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THE -LINKER - PHASE II 

B OBTAINING THE OFFSET VALUE 

I LOCATE THE DEFINITION SECTION OF THE JUST FOUND SEGMENT 
I OBTAIN THE BIT COUNT FROM THE DIRECTORY 
I DIVIDE IT BY 36 
I SUBTRACT 1 



I THIS IS THE LOCATION OF THE OBJECT MAP POINTER; USE IT TO 
LOCATE THE OBJECT MAP 



I WITHIN THE OBJECT MAP FIND THE ADDRESS OF THE DEFINITION 
SECTION 
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THE LINKER - PHASE II 



(This' page Intentionally left blank) 
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THE LINKER - PHASE II 

I WALK THROUGH THE DEFINITION SECTION 
I THIS IS ANOTHER LINKED LIST 



I LOOK FOR A CHARACTER ON THE CHAIN THAT MATCHES THE SECOND 
NAME EXTRACTED FROM PHASE ONE. 



HARDWARE CAN USE 



I THE LINKER NOW HAS ALL THE INFORMATION NECESSARY TO SNAP THE 

LINK 



a SNAPPING THE LINK 



I BACK IN THE FAULTING OBJECT SEGMENT WAS AN UNSNAPPED LINK 



I THE LINKER WILL OVERWRITE THIS INFORMATION WITH THE NEWLY FOUND 
SEGMENT NUMBER AND OFFSET 



I THE LINKER WILL PLACE BINARY 100011 IN THE LAST SIX BITS OF THE 
FIRST WORD OF THE LINK 



I THE LINK IS NOW A STANDARD POINTER - IT IS SNAPPED 



I ANY FURTHER REFERENCES THROUGH THIS LINK WILL NOT RESULT IN A 
FAULT 
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THE LINKER - PHASE II 



I THIS SNAPPING DOES NOT EFFECT ANY OTHER LINK WITHIN THE LINKAGE 
SECTION 
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THE LINKER - PHASE II 
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THE LINKER - PHASE II 



a LOADING THE OBJECT SECTIONS 



I THE NEWLY REFERENCED SEGMENT MAY HAVE A LINKAGE AND STATIC 
SECTION OF ITS OWN THAT MUST BE LOADED INTO MEMORYY 



I THE DYNAMIC LINKER PERFORMS THE COPYING OF THE STATIC AND 
LINKAGE TEMPLATES INTO THE PROPER AREAS 



I IF THE LOT WORD CORRESPONDING TO THE SEGMENT IS EMPTY (I.E. LOT 
(SEGMENT NUMBER) =0) THEN THE LINKER WILL COPY IT 



I GET SOME ROOM IN THE COMBINED LINKAGE AREA FOR THE LINKAGE 
SECTION 



I COPY THE LINKAGE TEMPLATE FROM THE OBJECT INTO THE SPOT IN 
THE COMBINED LINKAGE AREA 



I PLACE THE ADDRESS OF THE LINKAGE SECTION INTO THE LOT ENTRY 



i • ftiKrUKM THE SAME WITH THE STATIC SEUT1UN, UblJNtj THE J.SUT AiNU 

COMBINED STATIC AREA 



I NOTE: THE STATIC MAY BE COMBINED WITH THE LINKAGE 
INFORMATION, IN WHICH CASE THE STATIC WAS LOADED WITH THE 
LINKAGE SECTION 
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THE LINKER - PHASE II 
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THE LINKER - PHASE II 

a INSTRUCTION RETRY 

I RETURN TO THE SCENE OF THE CRIME 

I WHEN link snap IS FINISHED, IT RETURNS TO fim 



I fim THEN CAUSES THE INSTRUCTION THAT GENERATED THE LINKAGE 
FAULT TO BE RESXECUTED 



I WITH THE LINK NOW SNAPPED, A FAULT WILL NOT OCCUR AND THE 
INSTRUCTION WILL FIND THE THING IT WAS LOOKING FOR 
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THE LINKER - PHASE II 
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BY-PRODUCTS OF DYNAMIC LINKING 



a INITIATION 



I EVERY SEGMENT THAT A PROCESS WANTS TO USE MUST BE REGISTERED 
WITH BOTH THE dseg AND kst 

JfiSctiflOS- $<>•> 

I IF A SEGMENT IS NOT REGISTERED - KNOWN - TO A PROCESS AND IT IS 
THE OBJECT OF A LINKAGE FAULT, THEN THE DYNAMIC LINKER WILL MAKE 
IT KNOWN 



I THIS INVOLVES GOING TO THE kst, FINDING OUT THE NEXT FREE 
NUMBER TO USE AND ASSIGNING IT TO THE NEW SEGMENT 



I BECAUSE THIS IS PRETTY MUCH AN UNPREDICTABLE OPERATION AS FAR 
AS AVAILABLE NUMBERS ARE CONCERNED, MULTICS DOES NOT 
GUARANTEE THE CONSISTENCY OF SEGMENT NUMBERS ACROSS PROCESS 
BOUNDARIES 



a HIDDEN DANGERS 



I THE SEARCH FOR A SEGMENT TO FULFILL THE LINKAGE FAULT CAN CREATE 
DANGERS FOR PROGRAMMERS WHO ARE NOT AWARE OF THE NATURE OF THE 
SEARCH 



I CONSIDER THE FOLLOWING SCENARIO 

I A PROGRAMMER HAS WRITTEN A SET OF PROGRAMS 

THE FIRST PROGRAM IS CALLED driver 

IT CALLS calculate_total 

IT THEN CALLS ioa_ TO PRINT THE TOTAL OUT 

LATER (AND ALTHOUGH UNLIKELY, POSSIBLE) driver CALLS A 
PROGRAMMER PROVIDED PROGRAM NAMED formline 
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BY-PRODUCTS OF DYNAMIC LINKING 



I THERE IS A SIGNIFICANT CHANCE THAT THE PROGRAMMER SUPPLIED 
formline WILL NOT EXECUTE 



I THE MULTICS SYSTEM SUBROUTINE, ioa_, ALSO CALLS A PROGRAM 
NAMED formline_ 

IF ioa_ TOOK A LINKAGE FAULT WHILE CALLING formline , IT 
WOULD HAVE FOUND THE SYSTEM'S COPY USING THE ref erencing_dir 
RULE, PLACED S NAME IN THE RNT, AND driver WOULD HAVE FOUND 



I NOTE, THEN THAT IT IS POTENTIALLY DANGEROUS TO CALL PROGRAMS 
OUTSIDE THE DIRECTORY OF EXECUTION IF THE NAMES OF SEGMENTS CAN 
BE DUPLICATED ELSEWHERE 



I BINDING ALSO HELPS 



a BINDING 



I BINDING ITSELF IS A LINKING PROCESS, BUT ITS EFFECTS CAN 32 FELT 
SYSTEM WIDE 



I THIS EXPLANATION WILL CONCERN ITSELF WITH ONLY THE* LINKING 
ASPECTS OF BINDING 



I ONE OF THE ADVANTAGES OF DYNAMIC LINKING IS THAT UNUSED EXTERNAL 
REFERENCES WERE NOT LINKED, SAVING TIME 



I IF A SET OF PROGRAMS MAKE MANY CALLS TO EACH OTHER AND IT IS 
ALMOST UNAVOIDABLE THAT ALL LINKS WILL 3E SNAPPED IN THE COURSE 
OF THEIR EXECUTION, THEN PRELINKING WILL BE CHEAPER 
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BY-PRODUCTS OF DYNAMIC LINKING 



I EACH LINK WILL BE SNAPPED ONCE IN ITS LIFE, AS OPPOSED TO 
MANY TIMES WITH DYNAMIC LINKING 



I THE PROGRAMMER MUST GIVE UP THE ABILITY TO MAKE CHANGES TO 
OBJECT EASILY; THEREFORE BINDING SHOULD 3E DONE ONLY AFTER 
THE PROGRAMS ARE FULLY DEBUGGED 



I THE BINDER'S TASK 

I BREAK APART ALL THE SECTIONS OF ALL THE PROGRAMS TO BE BOUND 
I GROUP ALL LIKE SECTIONS TOGETHER (TEXT WITH TEXT, ETC) 



I COMBINE ALL THE LINKAGE SECTIONS TOGETHER, AND ELIMINATE ALL 
LINK DUPLICATIONS 



I ELIMINATE SOME SNTRYPOINTS INTO THE PROGRAMS, TRIMMING DOWN 
THE DEFINITION SECTION 



I GENERATE ONE OBJECT MAP AND OBJECT MAP POINTER 



I A BOUND SEGMENT MAY ACTUALLY HAVE LINKS LEFT OVER THAT WERE NOT 
RESOLVED AT BINDING TIME; THEY WILL BE HANDLED BY THE DYNAMIC 
LINKER WHEN NEEDED 
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The Multics Programming Environment 7-1 

Destruction of the Programming Environment. . 7-1 

Error Recovery Techniques 7-8 

The Multics Programming Environment 7-1 

Destruction of the Programming Environment. . 7-1 

Error Recovery Techniques 7-8 



7-i 



Topic VII MULTICS PROGRAMMING ENVIRONMENT Topic VII 



OBJECTIVES: 



Upon completion of this topic* students should be able to! 



1. Discuss some of the ways in which the Multics process 
environment can be disrupted. 



process to terminate abnormally. 



3. Apply preventive techniques during program development to 
minimize the number of potentially danserous proarammins 
errors . 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 

I SOURCE SEGMENT 

I WHEN INITIATED 3Y THE COMPILER, NOT GIVEN A REFERENCE NAME 
I USUALLY NOT MADE KNOWN EXCEPT BY COMPILER 

I SEGMENT USUALLY NOT KNOWN 

I DESTRUCTION UNLIKELY 

I OBJECT SEGMENT 

I SEGMENT READ-EXECUTE ONLY (EXCEPT WHEN DEBUGGER IS SETTING 
BREAKPOINTS) 

I DESTRUCTION UNLIKELY BECAUSE OF HARDWARE PROTECTION 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 

B stack_n SEGMENT 

I IN [pd] 

I READ-WRITE 

I INCLUDES 

I PROGRAM ACTIVATION HISTORY (STACK) 

1 AUTOMATIC VARIABLES 

I STACK HEADER INFORMATION 

I INCLUDES INITIAL LOT & ISOT ALLOCATIONS 



I DESTRUCTION POSSIBLE THROUGH MISUSE OF AUTOMATIC VARIABLES OR 
BUILT-IN FUNCTIONS 



I SUBSCRIPTRANGE 

I STRINGRANGE 

I USE OF UNINITIALIZED POINTER TO BASED VARIABLE 

I SYMPTOMS 

I IF STACK HEADER OVERWRITTEN, FATAL PROCESS ERROR USUALLY 
OCCURS 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 



I STRINGRANGE OFTEN RESULTS IN STORAGE CONDITION (out_of_bounds 
ON USER'S STACK) 



1 SUBSCRIPTRANGE CAUSES AUTOMATIC DATA AND/OR PROGRAM 
ACTIVATION INFORMATION TO BE OVERWRITTEN, LEADING TO IMPROPER 
RESULTS AND PROGRAM OPERATION 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 

[ unique] .area . I Inker SEGMENT 

I IN [pd] 

I READ-WRITE AREA 

I INCLUDES 

I COMBINED LINKAGE AREA 
I LINKAGE SECTIONS 
I LOT 
I ISOT 
I ' RNT 

I COMBINED STATIC AREA 

I INTERNAL STATIC SECTIONS (VARIABLES) 

I USER FREE AREA 

I EXTERNAL STATIC AND COMMON VARIABLES - PER PROCESS 

I EXTERNAL VARIABLE CONTROL INFORMATION 

I CONTROLLED VARIABLES 

I BASED VARIABLES - NO AREA, IN AN I/O BUFFER 

I COBOL VARIABLES 

I ASSIGNED LINKAGE AREA 

I BASED STORAGE-ALLOCATED THROUGH hcs_$assign_linkage 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 

a [unique] .area. linker SEGMENT (continued) 

I DESTRUCTION POSSIBLE THROUGH 
I SUBSCRIPTRANGE 
1 STRINGRANGE 

I USE OF UNINITIALIZED POINTERS 
I MISUSE OF AREA 

I -g&serm] same bas-s o variable twice - 

I SYMPTOMS 

I IF LINKAGE SECTIONS OVERWRITTEN, IMPROPER PROGRAM OPERATION 

I IF LOT OVERWRITTEN, IMPROPER OPERATION OF ALL PROGRAMS 

I IF ISOT OVERWRITTEN, IMPROPER INTERNAL STATIC DATA; 
SUBSEQUENT DESTRUCTION OF OTHER DATA 

I IF RNT OVERWRITTEN, UNABLE TO FIND PREVIOUSLY-REFERENCED 
PROGRAMS 



I IF VARIABLES (OF ANY STORAGE CLASS) ARE OVERWRITTEN, IMPROPER 
VARIABLE VALUES 



I IF EXTERNAL VARIABLE CONTROL INFORMATION OVERWRITTEN, 
IMPROPER COMMUNICATION OF SHARED VARIABLES BETWEEN PROGRAMS; 
IMPROPER DATA VALUES 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 



I IF AREA CONTROL INFORMATION OVERWRITTEN, bad_area_f ormat 
CONDITION 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 



DIRECTORIES, dseg, kst 



I NO DIRECT ACCESS TO USER FROM USER RING {RING 4) 



I DESTRUCTION UNLIKELY, SEGMENTS PROTECTED 3Y HARDWARE 
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ERROR RECOVERY TECHNIQUES 



3 MOST ERRORS WHICH DESTROY THE PROGRAMMING ENVIRONMENT 



I ARE CAUSED BY IMPROPER SUBSCRIPTS, BAD SUBSTRING OPERANDS, OR 
POINTERS USED IMPROPERLY 



I RECOVERY FROM SUBSCRIPTRANGE AND STRINGRANGE 



I RECOMPILE PROGRAMS CAUSING THESE ERRORS AND ENABLE CHECKING 
FOR THESE CONDITIONS 



I PL/1: INSERT A LINE CONTAINING 



\ (size, string size, string range, subscriptrange) : 

AT THE BEGINNING OF EACH SOURCE SEGMENT, AND RECOMPILE 
WITH -table OPTION 

I COBOL: USE -runtirae_check AND -table CONTROL ARGUMENTS IN 
cobol COMMAND 

1 FORTRAN: USE -subscriptrange AND -table CONTROL ARGUMENTS 
IN fortran COMMAND 



I RUN PROGRAMS 

I IF CONDITIONS ARE SIGNALLED, USE probe TO FIND CAUSE 



I FIX PROBLEMS, AND RECOMPILE AS ABOVE UNTIL NO MORE CONDITIONS 
ARE SIGNALLED 



I IF NO MORS CONDITIONS ARE SIGNALLED, BUT PROGRAMMING 
ENVIRONMENT ERRORS STILL PERSIST 

I RECOMPILE WITHOUT THE CONDITION CHECKING, 3UT WITH -table 
CONTROL ARGUMENT 

I PROCEED AS GIVEN BELOW UNDER "FURTHER ERROR RECOVERY" 
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ERROR RECOVERY TECHNIQUES 



I IF ALL ERRORS CORRECTED, RECOMPILE WITHOUT CONDITION CHECKING 
OR -table 



a FURTHER ERROR RECOVERY 

I bad_area_forniat CONDITION IN [unique] .area.linker SEGMENT 

I CAUSED BY OVERWRITING AREA CONTROL INFORMATION 
I STORED AT BEGINNING OF AREA 
I STORED BETWEEN SPACE ALLOCATIONS 



I RECOVERY TECHNIQUES (ASSUMES STRINGRANGE AND SUB SCRIPT RANGE 
TESTS HAVE ALREADY BEEN DONE) 

I USE area_status COMMAND TO FIND FAULTY LOCATION IN AREA 

I USE dump__segment COMMAND TO PRINT AREA AROUND THAT 
LOCATION; RECOGNIZABLE DATA MAY LEAD TO THE CAUSE 

I USE create_area AND set_user_storage COMMANDS TO SEPARATE 
USER FREE AREA FROM OTHER GROUPED AREAS 

I IF ERROR OCCURS NOW IN USER-SPECIFIED AREA SEGMENT, THEN 
PROBLEM' IS IN A USER PROGRAM (NO SYSTEM PROGRAMS EXCEPT 
EXTERNAL VARIABLE MANAGER USE THIS AREA) 

I USE probe TO EXAMINE ALL POINTER-QUALIFIED REFERENCES TO 
BE SURE POINTER IS SET PROPERLY 



I AFTER BAgED~-VARXAJ L I t g : S 1 . -HAVE — B-EEN~"TREED , NU LL THEIR POINTER 
TO ,XBilV-SN-T-^UBSEQUENT~RETERENCE TO TRTEI3~STSCE 
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ERROR RECOVERY TECHNIQUES 






I FATAL PROCESS ERRORS (REPRODUCIBLE) 

I CAUSED BY OVERWRITING 

I STACK HEADER 

I LINKAGE OR INTERNAL STATIC SECTIONS OF CRITICAL PROGRAMS 
(iox_, listen_, command_processor__, pr int_ready__msg_, 

etc.) 

I RECOVERY TECHNIQUES 

I ATTEMPT TO ISOLATE POINT OF PROCESS FAILURE TO A SINGLE 
PROGRAM STATEMENT 

I USE probe TO 

I SET BREAKS AT KEY POINTS IN THE EXECUTION OF THE 
PROGRAM 

I CONTINUE EXECUTION AS EACH BREAK IS REACHED UNTIL FATAL 
ERROR OCCURS 

I WHEN FATAL ERROR OCCURS, POINT OF FAILURE LIES AFTER 
LAST BREAKPOINT WHICH WAS REACHED 

I SET BREAKS AFTER THIS POINT TO FURTHER ISOLATE POINT OF 
FAILURE TO A SINGLE STATEMENT 

I FAILING STATEMENT MAY BE 

I CAUSE OF ERROR 

I USING INCORRECT DATA AS RESULT OF A PREVIOUS ERROR 
I USE probe TO TRACK ORIGINAL CAUSE OF ERROR 

. I USE -watch CONTROL ARGUMENT OF trace COMMAND TO ISOLATE 
THE SUBROUTINE WHICH IS DAMAGING A PARTICULAR DATA ITEM 
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ERROR RECOVERY TECHNIQUES 

a FURTHER "ERROR RECOVERY (continued) 

I FATAL PROCESS ERRORS (INTERMITTENT) 

I CAN BE CAUSED BY 

I UNINITIALIZED DATA VALUES 



I RECOVERY TECHNIQUES 

I IN A NEW PROCESS, RUN JUST THE FAILING PROGRAM 

X IF PROGRAM OPERATES CORRECTLY, ANOTHER PROGRAM MAY BE 
SOURCE OF ERROR 

I IF PROGRAM FAILS (ESPECIALLY FAILS INTERMITTENTLY OR IN 
DIFFERENT WAYS) , USE probe TO LOOK FOR UNINITIALIZED 
VARIABLES 
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Topic VIII OTHER DEBUGGING COMMANDS Topic VIII 

OBJECTIVES: 

Upon completion of this topic, students should be able to: 

1. Manipulate external variables with the following commands: 

list_external_variables (lev) 
reset_external_variables (rev) 
delete_external_variables (dev) 



2. Find and correct problems related to linking with the 
following commands: 



print_bind_map (pfam) 
print_link_inf o (pli) 
resolve_l inkase-error (rle) 



3. Use the trace_stack (ts) command in conjunction with trace 
and probe to determine the state of the process when an error 
occurs. 
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list external variables 



guie ' Xi.au CACckuctA voliciOISS 

The list_external_variables command prints information about 
variables managed by the system for the user, including FORTRAN common 
and PL/I external static variables whose names do not contain dollar 
signs. The default information is the location and size of each 
specified variable. 

Usage 

list_external_variables names { -control_args} 

where : 

1. names 

are names of external variables, separated by spaces. 

2. control_args 

can be chosen from the following: 

-unlabeled_common, -uc 

is the name for unlabeled (or blank) common. 

-long, -Ig 

prints how and when the variables were allocated. 

-all, -a 

prints information for each variable the system is 
manag ing . 

-no_header, -nhe 

suppresses the header. 
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reset external variables 



Name : reset_external_variables 

The reset_external_variables command reinitializes system-managed 
variables to the values they had when they were allocated. 

Usage 

reset_external_variables names { -control_arg} 

where : 

1. names 

are the names of the external variables, separated by 
spaces, to be reinitialized. 

2. control arg 

Ts -unlabeled_common (or -uc) to Indicate unlabeled (or 
block) common. 



Note 

A variable cannot be reset if the segment containing 
the initialization information is terminated after the 
variable is allocated. 
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delete external variables 



Name: delete_external_variables 

The delete external_variables command deletes from the user's 
name space specified variables managed by the system for the user. 
All links to those variables are unsnapped and their storage is freed. 

Usage 

delete_external_variables names { -control_arg} 

where: 

1. names 

are the names of the external variables, separated by 
spaces, to be deleted. 

2. control arg 

Ts -unlabel ed_common (or -uc) to indicate unlabeled (or 
blank) common. 
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print bind map 



Name: pr int_bind_map 

The print_bind_map command displays all or part of the bind map 
of an object segment generated by version number 4 or subsequent 
versions of the binder. 

Usage 

print_bind_map path {components} { -control__args} 

wh e r e : 

1. path 

is the pathname of a bound object segment. 

2. components 

are the optional names of one or more components of this 
bound object and/or the bindfile name. Only the lines 
corresponding to these components are displayed. A 
component name must contain one or more 'nonnumeric 
characters. If it is purely numerical, it is assumed to 
be an octal offset within the bound segment and the lines 
corresponding to the component residing at that offset are 
displayed. A numerical component name can be specified by 
preceding it with the -name control argument (see below) . 
If no component names are specified, the entire bind map 
is displayed. 

3. control_args- 

may be chosen from the following list: 

-long, -lg 

prints the components' relocation values {also printed in 
the default brief mode) , compilation times, and source 
languages. 

-name STR, -nm STR 

is used to indicate that STR is really a component name, 
even though it appears to be an octal offset. 

~no_header, -nhe 

omits all headers, printing only lines concerning the 
components themselves. 
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print link info, pli 



Name: pr int_link_info , pli 

The print_link_info command prints selected items of information 
for the specified object segments. 

Usage 

print_link_info paths {-control__args} 

where : 

1. paths 

are the pathnames of object segments. 

2. control_args 

can be chosen from the following list. (See "Note" 
below. ) 

-length, -In 

■ print only the lengths of the sections in pathi. 

-entry, -et 

print only a listing of the pathi external definitions, 

giving their symbolic names and their relative addresses 

within the segment. 

-link, -Ik 

print only an alphabetically sorted listing of all the 
external symbols referenced by path_i. 

-long . . , 

prints more information- when the header is printed. 

Additional information includes a listing of source 

programs used to generate the object segment, the contents 

of the "comment" field of the symbol header (often 

containing compiler options) , and any unusual values in 

the symbol header. 

-header, -he 

prints the header (The header is not printed by default, 
if the -length, -entry, or -link control argument is 
specified .) 

-no__header 

suppresses printing of the header. 

Note 

Control arguments can appear anywhere on the command line and 
apply to all pathnames. 
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Example 

! pr int_link_info program -long -length 

program 07/30/76 1554.2 edt Fri 

Object Segment >udd>Work>Wilson> prog ram 
Created on 07/30/76 0010.1 edt Fri 
by Wilson. Work. a 

using Experimental PL/I Compiler of Thursday, July 26, 1976 at 21:38 

Translator: PL/I 

Comment: map table optimize 

Source: 

07/30/76 0010.1 edt Fri >user_dir_dir>work>Wilson>s>s>prograa.pll 

12/15/75 1338.1 edt Mon >library_dir_dir> include)- linkdcl . incl .pll 

06/30/75 1657.7 edt Mon >library_dir_dir> include>object_inf o . incl .pll 

10/06/72 1206.8 edt Fri >library_dir_dir> include>source_map. incl .oil 

05/18/72 1512.4 edt Thu >library_dir_dir> include>symbol_block .incl .pll 

01/17/73 1551.4 edt Wed >library_dir_dir> include>pll_symbol_block . incl .pll 

Attributes: relocatable, procedure, standard 

Object Text Defs Link Symb Static 

Start 3450 3620 3656 3630 

Length 11110 3450 150 36 5215 



<ready> 



Also printed is: 

Severity, if it is nonzero. 
Entrybound, if it is nonzero. 
Text Boundary, if it is not 2. 
Static Boundary, if it is not 2, 
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Name ; resolve__linkage_error , rle 

The resolve_linkage_error command is invoked to satisfy the 
linkage fault after a process encounters a linkage error. The program 
locates the virtual entry specified as an argument and patches the 
linkage information of the process so that when the start command is 
issued the process continues as if the original linkage fault had 
located the specified virtual entry. 

resolve_linkage_error virtual_entry 
where virtual_entry is a 'virtual entry specifier. 

Notes 

For an explanation of virtual entries, see the description of the 
cv entry subroutine. 



Examples 



myprog 

Error: Linkage error by >udd>m>vv> myprog 1 123 

referencing subroutine$entry 

Segment not found. 

r 1234 2.834 123.673 980 level 2, 26 

rle mysub$mysub_entry 

r 1234 0.802 23.441 75 level 2, 26 

start 

. . . myprog is running 



Not To Be Reproduced 8-7 F21 



trace stack, ts 



Name: trace_stack , ts 

The trace_stack command prints a detailed explanation of the 
current process stack history in reverse order (most recent frame 
first) . For each stack frame, all available information about the 
procedure that established the frame (including, if possible, the 
source statement last executed) , the arguments to that (the owning) 
procedure, and the condition handlers established in the frame are 
printed. For a description of stack frames, see "Multics Stack 
Segments" in Section! IV of the MPM Subsystem Writers* Guide. 

The trace_stack command is most useful after a fault or other 
error condition. If the command is invoked after such an error, the 
machine registers at the time of the fault are also printed, as well 
as an explanation of the fault. The source line in which it occurred 
can be given if the object segment is compiled with the -table option. 

Usage 

trace_stack {-control_args} 

where control_args can be selected from the following: 

-brief, -bf 

suppresses listing of arguments and handlers. This 
control argument cannot be specified if -long is also 
specified as a control argument. 

-long, -lg 

prints octal dump of each stack frame. 

-depth N, -dh N 

dumps only N frames. 

Output Format 

When trace_stack is invoked, it first searches 
backward through the stack for a stack frame containing 
saved machine conditions as the result of a signalled 
condition. If such a frame is found, tracing proceeds 
backward from that point; otherwise, a comment is printed 
and tracing begins with the stack frame preceding 
trace_stack . 

If a machine-conditions frame is found, trace_stack 
repeats the system error message describing the fault. 
Unless the -brief control argument is specified, 
trace_stack also prints the source line and faulting 
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instruction and a listing of the machine registers at the 
time the error occurred. 



The command then performs a backward trace of the 

stack, for N frames if the -depth N argument was 

specified, or else until the beginning of the stack is 
reached. 



For each stack rrame, trace_stacK prints <-x 
of the frame, the condition name if an error occurred in 
the frame, and the identification of the procedure that 
established the frame. If the procedure is a component of 
a bound segment, the bound segment name and the offset of 
the procedure within the bound segment are also printed. 

The trace_stack command then attempts to locate and 
print the source line associated with the last instruction 
executed in the procedure that owns the frame (that is, 
either a call forward or a line that encountered an 
error). The source line can be printed only if the 
procedure has a symbol table (that is, if it was compiled 
with the -table option) and if the source for the 
procedure is available in the user's working directory. 
If the source line cannot be printed, trace_stack prints a 
comment explaining why. 

Next, trace_stack prints the machine instruction last 
executed by the procedure that owns the current frame. If 
the machine instruction is a call to a PL/I operator, 
trace_stack also prints the name of the operator. If the 
instruction is a procedure call, trace_stack suppresses 
the octal printout of the machine instruction and prints 
the name of the procedure being called. 

Unless the -brief control argument is specified, 
trace_stack lists the arguments supplied to the procedure 
that owns the current frame and also lists any enabled 
condition, default, and clean-up handlers established in 
the frame. 



If the -long control argument is specified, 
trace_stack then prints an octal dump of the stack frame, 
with eight words per line. 
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Example 

After a fault that reenters the user environment and 
reaches command level, the user invokes the trace_stack 
command . 

For example, after quitting out of the list command, 
the following process history might appear: 

1 list 

Segments=8, Records=3 

rew mailbox 

r w 

QUIT 

1 trace_stack 

quit in ipc_$biockl 156 

(>system_iibrary_l>bound_command_loop_! 156) 
No symbol table for ipc_ 
156 400010116100 cmpq pr4i!0 

Machine registers at time of fault 

pro (ap) 26314656 pll_operators_$operator_table! 162 

(external symbol in separate nonstandard 
text section) 

prl (ab) 103 1264 scs|264 

pr2 (bp) 14112200 as_linkage| 12200 

pr3 (bb) 113 10 tc_data!0 

pr4 (lp) 25312250 1BBBJG jFkPBWcNZ .area . 1 inker I 2250 

(internal staticlO for ipc_) 

pr5 (lb) 244 13614 stack_4 1 3614 

pr6 (sp) 244 13500 stack_4 13500 ( -> "kcpMbLH +0000000") 

pr7 (sb) 244 10 stack_4|0 

x0 73 xl x2 x3 600000 
x4 x5 32 x6 3033 x7 4 
a 000000000000 q 000000000004 e 
Timer reg - 1746005, Ring alarm reg - 

SCU Data: 

4030 400270250011 000000000021 400270000000 000000672000 
000156000200 000154000700 002250370000 600044370120 

Connect Fault (21) 

At: 270 1156 ipc_J156 ( bound_command_loop_! 1 56) 

On: cpu a (#0) 

Indicators: *bar 
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APU Status: xsf, sd-on, pt-on , fabs 
CU Status: rfi, its, f if 
Instructions : 

4036 002250 3700 00 epp4 2250 

4037 6 00044 3701 20 epp4 pr6|44,* 

Time stored: 08/02/77 1635.5 edt Tue (104541674361226602) 
Ri ng : 4 

Backward trace of stack from 244 13500 

3500 quit ipc_$blockl 156 (bound_command_loop_i 156) 
No symbol table for ipc__ 
156 400010116100 cmpq pr4|10 

ARG 1: 25315704 1 BBBJGj FkPBWcNZ .area . 1 inker I 5704 
ARG 2: 244 13152 stack_4|3152 
ARG 3: 

2720 tty_$tty_get_iinel 2 44 2 (bound_iox_| 11546) 
No symbol table for tty_ 
call_ext_out to ipc_$block 

ARG 1: 25314320 I BBBJGj FkPBWcNZ .area . 1 inker 1 4 320 

(internal static! 154 for find_iocb) 
ARG 2: 244 12660 stack_4 12660 ( -> "fa stuff") 
ARG 3: 128 
ARG 4 : 
ARG 5: 

2400 listen_$listen_l 461 (bound_command_loop_| 1325) 
No symbol table for listen_ 
call_ext_out to iox_$get_line 

ARG 1 : " " 

on "cleanup" call listen_l256 (bound_command_loop_! 1122) 

2100 process overseer_$process_overseer_| 473 (bound_command__loop_J 214 

No symbol table for process_over seer_ 
call_ext_out_desc to listen_$listen_ 
Argument list header invalid, 
on "any_other" 

call standard_defaul t_handler_$standard_defaul t_handler_3 
(external symbol in separate nonstandard text section) 

2000 user ini t_admin_$user_ini t_admin_i 36 (bound_command__loop_| 21676) 

No symbol table for user_init_admin_ 
21676 700036670120 tsp4 pr7|36,* alm_call 

No arguments. 

End of trace. 
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r 1635 1.756 40.790 207 level 2, 9 
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Name : area_status 

The area_status command is used to display certain information 
about an area. 



Usage 

area_status area name {-control args} 

where: 

1. area_name 

is a pathname specifying the segment containing the area 
to be looked at. 

2. control_args 

can be chosen from the following: 

-trace 

displays a trace of all free and used blocks in the area. 

-offset N, -ofs N 

specifies that the area begins at offset N (octal) in the 
given segment. 

-long, -Ig 

dumps the contents of each block in both octal and ASCII 
format. 
Note 

If the area has internal format errors, these are reported. The 
command does not report anything about (old) buddy system areas except 
that the area is in an obsolete format. 
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Name : cancel_cobol_program, ccp 

The cancei_coboi_program command causes one or more programs in 
the current COBOL run unit to be cancelled. Cancelling ensures that 
the next time the program is invoked within the run unit, its data is 
in its initial state. Any files that have been opened by the program 
and are still open are closed and the COBOL data segment is truncated. 
Refer to the run_cobol command for information concerning the run unit 
and the COBOL runtime environment. 



Usage 

cancel_cobol_program names {-control arg} 

where : 

1. names 

are the reference names of COBOL programs that are active 
in the current run unit. If the name specified in the 
PROG-ID statement of the program is different from its 
associated namei argument, name_i must be in the form 
refname$ PROG-ID. 

2. control__arg 

may be -retain data or -retd to leave the data segment 
associated with - the program intact for debugging purposes. 
(See "Notes" below.) 



Notes 

The results of the cancel cobol program command and the execution 
of the CANCEL statement from within a COBOL program are similar. The 
only difference is that if a namej, argument is not actually a 
component of the current run unit, an~"error message is issued and no 
action is taken; for the CANCEL statement, no warning is given in such 
a case. 

To preserve program data for debugging purposes, the -retain_data 
control argument should be used. The data associated with the 
cancelled program is in its last used state; it is not restored to its 
initial state until the next time the program is invoked in the run 
unit. 

Refer to the following related commands: 
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display cobol run unit, dcr 
stop_coB"ol run, scr 
run cobol, re 
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Name : create_area 

The create area command creates an area and initializes it with 
user-specified area management control information. 

Usage 

create area virtual_ptr {-control_args} 
where : 

1. virtual ptr 

Ts a virtual pointer to the area to be created. The 
syntax of virtual pointers is described in the cv__ptr_ 
subroutine description. If the segment already exists, 
the specified portion is still initialized as an area. 

2. control_args 

can be chosen from the following: 

-no freeing 

allows the area management mechanism to use a faster 
allocation strategy that never frees. 

-dont^free 

Ts used during debugging to disable the free mechanism. 
This does not affect the allocation strategy. 

-zero on_alloc 

Tnstructs the area management mechanism to clear blocks at 
allocation time. 

-zero on_free 

Tnstructs the area management mechanism to clear blocks at 
free time. 

-extend 

causes the area to be extensible, i.e., span more than one 
segment. This feature should be used only for perprocess, 
temporary areas. 

-size N 

specifies the octal size, in words, of the area being 
created or of the first component, if extensible. If this 
control argument is omitted, the default size of the area 
is the maximum size allowable for a segment. 

-id STR 

specifies a string to be used in constructing the names of 
the components of extensible areas. 
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Name : create_data_segment, cds 

The create__data__segment command translates a create_data_segment 
source program"" (CDS program) into an object segment. A listing 
segment is optionally created. These results are placed in the user's 
working directory. This command cannot be called recursively. 

The source for create_data_segment programs is standard PL/I with 
the restriction that the program include a call to the 
create_data_segment_ subroutine. The create data_segment_ subroutine 
creates a standard object segment from PL/I cfata structures passed to 
it as parameters. These data structures can be initialized with 
arbitrarily complex PL/I statements in the CDS program. (See the MPM 
Subroutines for a description of the create_data_segment_ subroutine. } 

Usage 

create data_segment path {-control arg} 

where: 

1. path 

is the pathname- of a CDS segment that is to be translated 

Into an object segment. Ij. patn uoes not nave a cds 

suffix, one is asssumed. However, the cds suffix must be 

the last component of the name of the source segment. 

2. control_arg 

can be -list (-Is) to produce a source listing of the CDS 
program used to generate the data segment followed by 
object segment information (as printed by the 
pr int_link_info command described in the MPM Subsystem 
Writers' Guide) about the actual object segment created. 

Note 

Since the create data_segment command invokes the PL/I compiler 
to first compile the 'CDS segment, any errors that the compiler finds 
are reported by its standard technique. If any errors with a severity 
greater than 2 occur, the CDS run is aborted and an object segment is 
not created. 



Not To Be Reproduced A-5 F21 



cumulative page trace, cpt 



Name : cumulative_page_trace, cpt 

The cumulative page trace command accumulates page trace data so 
that the total set of pages used during the invocation of a command or 
subsystem can be determined. The command accumulates data from one 
invocation of itself to the next. Output from the command is in 
tabular format showing all pages that have been referenced by the 
user's process. A trace in the format of that produced by the 
page trace command can also be obtained. 

The cumulative_page_trace command operates by sampling and 
reading the system trace - array after invocation of a command and at 
repeated intervals. Control arguments are given to specify the 
detailed operation of the cumulative_page_trace command. 

The command line used to invoke the cumulative__page_trace command 
includes the command or subsystem to be traced as well as optional 
control arguments. 

Usage 

cumulative page trace command_line {-control_args} 

where: 

1. command line 

Ts a character string to be interpreted by the command 
processor as a command line. If this character string 
contains blanks, it must be surrounded by quotes. All 
procedures invoked as a result of processing this command 
line are metered by the cumulative_page_trace command. 

2. control_args 

may be chosen from the following: 

-count, -ct 

prints the accumulated results, giving the number of each 
page and the number of faults for each page. 

-flush 

clears primary memory before each invocation of the 
command line and after each interrupt. This helps the 
user determine the number of page faults but increases the 
cost. 

-interrupt N -int N 

interrupts execution every N virtual CPU milliseconds for 
page fault sampling. 
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-long, -Ig 

produces output in long format, giving full pathnames. 

-loop N 

calls the command to be metered N times. 

-print, -pr 

prints the accumulated results, giving the number of each 
page referenced. 

~print_linkage faults 

prints aTl accumulated linkage faults and calls to the 
hcs_$maka__ptr entry point. 

-reset, -rs 

resets the table of accumulated data. If the table is not 
reset, data from the current use of cumulative_page trace 
is added to that obtained earlier in the process". 

-short, -sh 

formats output for a line length of 80. 

-sleep N 

waits for N seconds after each call to the command being 

metered. 

-timers 

includes all faults between signal and restart. " 

-total, -tt 

prints the total number of page faults, the total number 
of segment faults, and the number of pages referenced for 
each segment. 

-trace_iinkage faults 

accumulates linkage faults information along with page and 
segment fault information. 

-trace path 

writes the trace on the segment named path using an I/O 
switch named cpt. out; cumulative page trace attaches and 
detaches this switch. 



Notes 

At least one of three generic operations must be requested. They 
may all be combined and, if so, are performed in the following order: 
resetting the table of accumulated data, calling the command to be 
metered, applying the specified control arguments, and printing the 
results in the specified format. 
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The default mode of operation permits no interrupts for page 
fault sampling. If the command or subsystem to be metered will take 

more man sSvet ai uuitutcu pays i~au_i.v,5, iluSoys j-a ui u.j , Jl uuii = i jjji.'-'" 

events that are indicated in the page trace array, it is recommended 
that interrupts be requested. If the user does not know a suitable 
value for the -interrupt control argument, the value recommended is 
400 milliseconds. If this figure is too large, messages indicate that 
some page faults may have been missed; a smaller value can then be 
chosen. The cost of a smaller value is high and may cause additional 
side effects. If the command or subsystem to be metered includes the 
taking of CPUT interrupts, then the -timers control argument should be 
given. This control argument causes some of the page faults of the 
metering mechanism to be included as well. 

Only one of the control arguments -print, -count, or -total may 
be given. Each of these control arguments produces printed output in 
a different format. If more than one format is desired, the command 
must be invoked once for each format. 



Examples 

The command line: 

cpt "pll test" -interrupt 400 -trace trace_out 

calls the pll command to compile the program named test, requesting an 
interrupt every 400 milliseconds to obtain page trace information. 
Trace information is placed in a segment named trace_out. 

The command line: 

cpt "list -pn >udd>Multics" -loop 2 -sleep 10 
calls the list command twice, and sleeps for 10 seconds between calls. 

The command line: 
cpt -print 
prints the accumulated results of previous metering. 
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Name : cv ptr 

The cv_ptr_ subroutine converts a virtual pointer to a pointer 
value. A virtual pointer is a character string representation of a 
pointer value. The types of virtual pointers accepted are described 
under "Virtual Pointers" below. 



Usage 

declare cv_ptr_ entry (char(*), fixed! bin (35) ) returns! (ptr) ; 
ptr_value = cv_ptr_ (vptr, code); 



is the virtual pointer to be converted. (Input) 
See "Virtual Pointers" below for more information. 

is a standard status code. (Output) 

is the pointer that results from the conversion. 
(Output) 
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This entry point is called to terminate the segment that has been 
initiated bv a previous call to cv ptr . 



Usage 

declare cv_ptr_$ terminate (ptr) ; 
call cv_ptr_$ terminate (ptr_value) ; 

where ptr value is the pointer returned by the previous call to 
cv_ptr_. Tlnpuc) 

Notes 

Pointers returned by the cv ptr subroutine cannot be used as 
entry pointers in calls to cu $gen_call or cu $make_entry_value . The 
cv_ptr_ subroutine constructs the returned poTnter to a "segment in a 
way that avoids copying of the segment's linkage and internal static 
data into the combined linkage area. The cv entry subroutine is used 
to convert virtual entries to an entry value. ~ 
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The segment pointed to by the returned ptr_value is initiated 
with a null reference name. The cv_ptr_$ terminate entry point should 
be called to terminate this null reference name. 

Virtual Pointers 

The cv__ptr subroutine converts virtual pointers that contain one 
or two components — a segment identifier and an optional offset into 
the segment. Altogether, fourteen forms are accepted. They are shown 
in the table below. 

In the table that follows, W is an octal word offset from the 
beginning of the segment. It may have a value from to 777777 
inclusive. B is a decimal bit offset within the word. It may have a 
value from to 35 inclusive. 
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Virtual 

Pointer Interpretation 



path|W(3) points to octal word W, decimal bit B of segment 

identified by absolute or relative pathname path. 

path!W same as path|W{0). 

path! same as path|0(0). 

path same as pathiO(O). 

path I entry pt points to word identified by entry point entry_pt 

"* in segment identified by path. 

ref_name$entry_pt points to word identified by entry point entry_Pt 

in segment whose reference name is ref__name. 

ref name$W(B) points to octal word W, decimal bit B of segment 

whose reference name is ref_name. 

ref natneSW same as ref name$W(0). 

ref_name$ same as ref_name$0 (0) . 

segno! W(3) points to octal word VI, decimal bit 3 of segment 

"whose octal segment number is segno. 

segno | W same as segno|W(0). 

segno I same as segno|0(0). 

segno same as segno|0(0). 

segno I entry_pt points to word identified by entry point entry_pt 

in segment whose octal segment number is segno. 

A null pointer is represented by the virtual pointer 77777 11, by -111, 
or by -1 . 
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Name : delete external variables 

The delete external variables command deletes from the user's 
name space specTfied variables managed by the system for the user. 
All links to those variables are unsnapped and their storage is freed. 



Usaqe 



delete external variables names {-control arg} 



where: 

1. names 



are the names of the external variables, separated by 
spaces, to be deleted. 



2. control arg 

Ts -unlabel ed_common (or -uc) to indicate unlabeled (or 
blank) common. 



Not To 3e Reproduced 



A-12 



F21 



display cobol run unit, dcr 



The display_cobol_run_unit command displays the current state of 
a COBOL run unit. The "minimal information displayed tells which 
programs compose the run unit. Optionally, more detailed information 
can be displayed concerning active files, data location, and other 
aspects _of the run unit. Refer to the run_cobol command for 
information concerning the run unit and the COBOL runtime environment. 

Usage 

display_cobol_run_unit {-control args} 

where control__args may be chosen from the following list: 

-long, -Ig 

causes more detailed information about each COBOL program 
in the run unit to be displayed. 

-files 

displays information about the current state of the files 
that have been referenced during the execution of the 
current run unit. 

-all, -a 

prints information' about all programs in the run unit, 
including those that have been cancelled. 



Refer -to the following related -commands: 



run_cobol , re 
stop_cobol_run , scr 
cancel cobol program, ccp 
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Name: display_pllio_err , dpe 

The display pllio error command is designed to be invoked after 
the occurrence oT an l7o error signal during a PL/I I/O operation. It 
describes the most recent file on which a PL/I I/O error was raised 
and displays diagnostic information associated with that type of 
error. 



Usage 






Example 

The command line: 

display_pllio_error 
might respond with the following display: 

Error on file afile 
Title: vfile_ afil 
Attributes 



le_ at lie 

: open input keyed record sequential 
Last i/o operation attempted: write from 

"write" operation conflicts with file "input" attribute 

"from" nnpratinn conflicts with file " inout" attribute. 



Attempted 



Acremp-cea write operation coninccs witn iue myuu ollliuuu 
Attempted "from" operation conflicts with file "input" attribute. 
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Name : dump segment, ds 

The dump_segment command prints, In octal or hexadecimal format, 
selected portions of a segment. It prints out either four or eight 
words per line and can optionally be instructed to print out an edited 
version of the ASCII, BCD, EBCDIC ( in 8 or 9 bits), or 4-bit byte 
representation. 

Usage 

dump_segmant path {first} {n__words} {-control__args} 

where: 

1. path 

is the pathname or (octal) segment number of the segment 
to be dumped. If path is a pathname, but looks like a 
number, the preceding argument should be the -name (or 
-nm) control argument (see below) . 

2. first 

is the (octal) offset of the first word to be dumped. If 
.both first and n words are omitted, the entire segment is 

dumped. 

3. n_words 

is the (octal) number of words to be dumped. If first is 
supplied and n words is omitted, 1 is assumed. 

4. control_args 

can be chosen from the following: 

-4bit 

prints out a translation of the octal or hexadecimal dump 
based on the Multics unstructured 4-bit byte. The 
translation ignores the first bit of each 9-bit byte and 
uses each of the two groups of four bits remaining to 
generate a digit or a sign. 

-address, -add 

prints the address (relative to the base of the segment) 
with the data. This is the default. 

-bed 

prints the BCD representation of the words in addition to 
the octal or hexadecimal dump. There are no nonprintable 
3CD characters, so periods can be taken literally. 

-block N, -bk N 

dumps words in blocks of N words separated by a blank 
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line. The offset, if being printed, is reset to initial 
value at the beginning of each block. 

•character, -ch, -ascii 

prints the ASCII representation of the words in addition 
to the octal or hexadecimal dump. Characters that cannot 
be printed are represented as periods. 

-ebcdicS 

prints the EBCDIC representation of each 9-bit byte in 
addition to the octal or hexadecimal dump. Characters 
that cannot be printed are represented by periods. 

-ebcdicS 

prints the EBCDIC representation of each eight bits in 
addition to the octal or hexadecimal dump. Characters 
that cannot be printed are represented by periods. If an 
odd number of words is requested to dump, the last four 
bits of the last word do not appear in the translation. 

-header , -he 

prints a header line containing the pathname 'or segment 
number) of the segment being dumped as well as the 
date-time printed. The default is to print a header only 
if the entire segment is being dumped, i.,e., neither the 
first nor the n_words arguments is specified. 

-hexS 

print.s the dumped words in hexadecimal vith nine 

hexadecimal digits per word rather than octal with 12 

octal digits per word. 

-hex9 

prints the dumped words in hexadecimal with eight 
hexadecimal digits per word rather than 12 octal digits 
per word. Each pair of hexadecimal digits corresponds to 
the low-order eight bits of each 9-bit byte. 

-long, -Ig 

prints eight words on a line. Four is the default. This 
control argument cannot be used with -character, -bed, 
-4bit, -ebcdic8, -ebcdic9, or -short. (Its use with these 
control arguments, other than -short, results in a line 
longer than 132 characters.) 

-name, — ran 

indicates that the following argument is a pathname even 
though it may look like an octal segment number. 

-no address, -nad 

~° does not print the address. 
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•no_header, -nhe 

suppresses printing of the header line even though the 
entire segment is being dumped. 

-no_offset, -nofs 

does not print the offset. This is the default. 

•offset N, -ofs N 

prints the offset (relative to N words before the start of 
data being dumped) along with the data. If N is not 
given, is assumed. 

-short, -sh 

compacts lines to fit on a terminal with a short line 
length. Single spaces are placed between fields, and only 
the two low-order digits of the address are printed, 
except when the high-order digits change. ■ This shortens 
output lines to less than 80 characters. 



Note 

Only -one of the control arguments: -ebcdicS, 
-ebcdic9, -character, -bed, or -4bit can be specified. 
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Name: 



io call, io 



The io__call command performs an operation on a designated I/O 
switch. 



Usage 



io call opname switchname {args} 



where: 

1. opname 



designates the operation to be performed. 



2. switchname 

is the name of the I/O switch. 



args 



may be one or more arguments, depending on the particular 
operation to be performed. 



The opnames permitted, followed by their alternate forms where 
applicable, are: 



attach 

close 

control 

delete_record , delete 

detach iocb , detach 

destroy iocb 

find^iocb 

get_chars 

get_line 

modes 

move attach 



look__iocb 

open - " 

position 

print iocb 

put_chars 

read_key 

read__ length 

read~record, read 

rewr ite_record , rewrite 

seek_key 

write record, write 



Usage is explained below under a separate heading for each 
designated operation. The explanations are arranged functionally 
rather than alphabetically. 

Unless otherwise specified, if a control block for the I/O switch 
does not already exist, an error message is printed on error_output 
and the operation is not performed. If the requested operation is not 
supported* for the switch's attachment and/or opening, an error message 
is printed on er ror_output . 
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The explanations of the operations cover only the main points of 
interest and, in general, treat only the cases where the I/O switch is 
attached to a file or device. For full details see the descriptions 
of the iox_ subroutine and the I/O modules in the MPM Subroutines and 
Section V, "Input and Output Facilities," in the MPM Reference Guide. 

Operation : attach 

io_call attach switchname modulename {args} 



where : 



modulename 

is the name of the I/O module to be used in the 
attachment. If module-name contains less-than (<) or 
greater-than (>) characters, it is assumed to be a 
pathname, otherwise, It is a reference name. 



2. args 



may be one or more arguments, depending on what is 
permitted bv the particular I/O module. 



This command attaches the I/O switch using the designated I/O 
module. The attach description is the concatenation of modulename and 
args separated by blanks. The attach description must conform to the 
requirements of the I/O module. If the I/O modulename is specified by 
a pathname, it is initiated with a reference name equal to the 
entryname. If the entryname or reference name does not contain a 
dollar sign ($), the attachment will be made by calling 
modulename$modulenameattach. If a dollar sign is specified, the entry 
point specified is called. See "Entry Point Names" in the MPM 
Reference Guide. 



If a control block for the I/O switch does not already exist, one 
is created. 



Operation : detach iocb, detach 
io = call detach switchname 

This command detaches the I/O switch, 
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Operation ; open 

io^call open switchname mode 

where mode is one of the following opening modes, which may be 
specified by its full name, or by an abbreviations 

stream_input , si keyed_sequential_input , ksqi 

stream_output , so keyed__sequential_output , ksqo 

stream~~input_output , sio keyed_sequential~update , ksqu 

eonnanTial in mil- crti rlirsrh innnt- A i 

sequential_output , sqo direct output , do 

sequential_input__output , sqio direct update, du 
sequential_update* , squ 

This command opens the I/O switch with the specified opening 
mode. 



Operation ; close 

io_call close switchname 

This command closes the I/O switch. 

Operation: get line 

io_call get_line switchname {N} {-control args} 

where ; 

1. N 

is a decimal number greater than zero specifying the 
maximum number of characters to be read. 

2. control args 

can be selected from the following: 

-segment path {offset}, -sm path {offset} 

specifies that the line read from the I/O switch is to be 
stored in the segment specified by path, at the location 
specified by offset. 

-nnl 

specifies that the newline character, if present, is 
deleted from-- the end of the line. 
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-nl 

specifies that a newline character is added to the end of 
the line if one is not present. 

-lines 

specifies that the offset, if given, is measured in lines 
rather than characters. This control argument only has 
meaning if the -segment control argument is also 
specified. 

This command reads the next line from the file or device to which 
the I/O switch is attached. If N is given, and the line is longer 
than N, then only the first N characters are read. 

If the -segment control argument is not specified, the line read 
is written onto the .1/0 switch user_output, with a newline character 
appended if one is not present and -nnl has not been specified. 

If the -segment control argument is specified, the line is stored 
in the segment specified by path. If this segment does not exist, it 
is created. If offset is specified, the line is stored at that 
position relative to the start of the segment. This is normally 
measured in characters, unless -lines has been used. If offset is 
omitted, the line is appended to the end of the segment. The bit 
count of the segment is always updated to a point beyond the newly 
added data. 

Operation : get chars 

io_call get_chars switchname N {-control_args} 

where : 

1. N 

is a decimal number greater than zero specifying the 
number of characters to read. 

2. control args 

can be selected from the same list as described under the 
get_line operation. 

This command reads the next N characters from the file or device 
to which the I/O switch is attached. The disposition of the 
characters read is the same as described under the get line operation; 
that is, they are written upon user_output if the -segment control 
argument is not specified, or stored in a segment if the -segment 
control argument is specified. 
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Operation : put_chars 

io_call put chars switchname {string} {-control_args} 

where: 

1. string 

may be any character string. 

2. control args 

r«an ha eal a^if a^ £v^m +• Vn a f a 1 1 ami nfl • 
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-segment path {length}, -segment path {offset} {length}, 

-sm path {length}, -sm path {offset} {length} 

specifies that the data for the output operation is to be 
found in the segment specified by pathname. The location 
and length of the data may be optionally described with 
offset and length parameters. 

-nnl 

specifies that a newline character is not to be appended 
to the end of the output string. 

-nl 

specifies that a newline character is to be added to the 
end of the output line if one is not present. 

-lines 

specifies that offsets and lengths are measured in lines 
instead of characters. 

The string parameter and the -segment control argument are 
mutually exclusive. If a string is specified, the contents of the 
string are the data output to the I/O switch. If the -segment control 
argument is specified, the data is taken from the segment specified by 
path, at the offset and length given. If offset is omitted, the 
beginning of the segment is assumed. If length is omitted, the entire 
segment is output. 

If the I/O switch is attached to a device, this command transmits 
the characters from the string or the segment to the device. If the 
I/O switch is attached to an unstructured file, the data is added to 
the end of the file. The -nl control argument is the default on a 
put chars operation: a newline character is added unless one is 
already present, or the -nnl control argument is specified. 



Not To Be Reproduced A-22 F21 



io call, io 

Operation : read_record, read 

io_call read_record switchname N {-control_args} 

where: 

1. N 

is a decimal integer greater than zero specifying the size 
of the buffer to use. 

2. control_args 

can be selected from the same list as described under the 
get_line operation. 

This command reads the next record from the file to which the I/O 
switch is attached into a buffer of length N. If the -segment control 
argument is not specified, the record (or the part of it that fits 
into the buffer) is printed on user_output. If the -segment control 
argument is specified, the record is stored in a segment as explained 
under the get_chars operation. 

Operation : write record, write 

io__call wr ite__record switchname {string} {-control args} 



1. string 



is any character string. 



2. control args 

may be selected from the same list as described under the 
put_chars operation. 

This command adds a record to the file to which the I/O switch is 
attached. If the string parameter is specified, the record is equal 
to the string. If the -segment control argument is specified, the 
record will be extracted from the segment as described under the 
put_chars operation. In either case, the -nnl control argument is the 
default: a newline character is added only if the -nT control 
argument is specified. If the file is a sequential file, the record 
is added at the end of the file. If the file is an indexed file, the 
record's key must have been defined by a preceding seek key operation. 
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Operation : rewr ite_record, rewrite 

io call rewrite record switchname {string} {-control__args} 

where: 

1. string 

is any character string. 

2. control_args 

may be selected from the same list as described under the 
put_chars operation. 

This command replaces the current record in the file to which the 
I/O switch is attached. The new record is either the string 
parameter, or is taken from a segment, as described under the 
wr ite__record operation. The current record must have been defined by 
a preceding read record, seek key, or position operation as follows: 

read record 

~" current record is the last record read. 

seek_key 

current record is record with the designated key. 

position 

current record is the record preceding the record to which 
the file was positioned. 

Operation : delete record, delete 

io_call delete_record switchname 

This command deletes the current record in the file to which the 
I/O switch is attached. The current record is determined as in 
rewrite record above. 
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Operation : position 

io_call position switchname type 

where type may be one of the following: 
bof 



eof 



sets position to beginning of file 



sets position to end of file 



forward N, fwd N, f N 

sets position forward N records or lines (same as reverse 
N) 

reverse N, rev N, r N 

sets position back N records (same as forward -N records) 

other 

any other numeric argument or pair of numeric arguments 
may be specified, but its function depends on the I/O 
module being used and may not be implemented for all I/O 
modules. 



This command positions the file to which the I/O switch is 
attached. If type is bof, the file is positioned to its beginning, so 
that the next record is the first record (structured files) , or so 
that the next byte is the first byte (unstructured files). If type is 
eof, the file is positioned to its end;' the next record (or next byte) 
is at the end-of-file position. If type is forward or reverse the 
file is positioned forwards or backwards over records (structured 
files) or lines (unstructured files). The number of records or lines 
skipped is determined by the absolute value of N. 

In the case of unstructured files, the next byte position after 
the operation is at a byte immediately following a newline character 
(or at the first byte in the file or at the end of the file); and the 
number of newline characters moved over is the absolute value of N. 



If the I/O switch is attached to a device, only forward skips 
(where type is forward) are allowed. The effect is to discard the 
next n lines input from the device. 
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Operation : seek key 

io_call seek_key switchname key 

where key Is a string of ASCII characters with l<l length! £1256 . 

This command positions the indexed file to which the I/O switch 
is attached to the record with the given key. The record's length is 
printed on user_output. Trailing blanks in the key are ignored. 

If the file does not contain a record with the specified key, it 
becomes the key for insertion. A following write_record operation 
adds a record with this key. 

Operation : read key 

io__call read_key switchname 

This command prints, on user output, the key and record length of 
the next record in the indexed" file to which the I/O switch is 
attached. The file's position is not changed. 

Operation ; read_length 

io__call read_length switchname 

This command prints, on user_output, the length of the next 
record in the structured file to which the I/O switch is attached. 
The file's position is not changed. 
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Operation : control 

io_call control switchname order {args} 

where : 

1. order 

Is one of the orders accepted by the I/O module used in 
the attachment of the I/O switch. 



2. args 



are additional arguments dependent upon the order being 
issued and the I/O module being used. 



This command applies only when the I/O switch is attached via an 
I/O module that supports the control I/O operation. The exact format 
of the command line depends on the order being issued and the I/O 
module being used. For more details, refer to "Control Operations 
from Command Level" in the appropriate I/O module in the MPM 
Subroutines. If the I/O module supports the control operation and the 
paragraph just referenced does not appear, it can be assumed that only 
control orders that do not require an info structure can be performed 
with the io call command, as a null in"ro_ptr is. used. (See the 
description of the iox_$control entry point and the I/O module's 
control operation, both in the MPM Subroutines.) 



io call modes switchname {string} {-control arg} 



where: 

1. string 



is a sequence of modes separated by commas. The string 
must not contain blanks. 



2. control_arg 

may be -brief or -bf. 

This command applies only when the I/O switch is attached via an 
I/O module that supports modes. The command sets only new modes 
specified in string, and then prints the old modes on user_output. 
Printing of the old modes is suppressed if the -brief control argument 
is used. 
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If the switch name is user i/o, the command refers to the modes 
controlling the user's terminalT See the I/O module tty subroutine 
description in the MPM Subroutines for an explanation oT applicable 
modes. 



Operation ; find_iocb 

io_call find^_iocb switchname 

This command prints, on user_output, the location of the control 
block for the I/O switch. If it does not already exist, the control 
block is created. 

Operation : look_iocb 

io__call look_iocb switchname 

This command prints, on user_output, the location of the control 
block for the I/O switch. If the I/O switch does not exist, an error 
is printed. 

Operation : move_attach 

io_call move_attach switchname switchname2 

where switchname2 is the name of a -second I/O switch. 

This command moves the attachment of the first I/O switch 
(switchname) to the second I/O switch ( switchname2) . The original I/O 
switch is left in a detached state. 

Operation : destroy__iocb 

io_call destroy_iocb switchname 

This command destroys the I/O switch by deleting its control 
block. The switch must be in a detached state before this command is 
used. Any pointers to the I/O switch become invalid. 

Operation : print_iocb 

io call print iocb. switchname 
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This command 
control block for 


prints, 
the I/O 


var tables . 





on user_output, all of the data in the 
switch, including all pointers and entry 
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attach switchname modulename {args} 

detach switchname 

open switchname mode 

close switchname 

get_line switchname {N} {-control_args} 

get__chars switchname N {-control_args} 

put_chars switchname {string} {-control args} 

read_record switchname N {-control_argsJ 

write_record switchname {string} {-control_args} 

rewrite_record switchname {string} {-control_args} 

delete_record switchname 

position switchname type 

seek_key switchname key 

read key switchname 

read_length switchname 

control switchname order {args} 

modes switchname {string} {-control__arg} 

find_iocb switchname 

look iocb switchname 



e a', 



destr 
pr int 



switchname switchname2 



oy_iocb switchname 
iocb switchname 



where: 

1. switchname 

is the name of the I/O switch. 

2. modulename 

is the name of I/O module used in the attachment. 



3. args 



are any arguments accepted by the I/O module used in the 
attachment. 



Not To Be Reproduced 



A-29 



F21 



io call, io 



4. mode 



6. string 

7 . type 



key 

order 



is one of the following modes: 

stream_input, si keyed_sequential_input , ksqi 

stream_output , so keyed_sequential~output , ksqo 

stream input output, sio keyed_sequential_update , ksqu 

sequential_input, sqi direct_input, d i"~ 

sequential_output , sqo direct_output , do 
sequential_input_output , sqio direct__update , du 
sequential_update , squ 

is a decimal number. 

is any character string. 

sets the file position. It can be: 

bof forward N 

eof reverse N 

other 

is a string of ASCII characters with !<! length! <_!256 . 

is one of the orders accepted by the I/O module used in 
the attachment of the I/O switch. 



10. control_args 

can be chosen from the following: 

-segment path {length}, -sm path {length} 

-segment path {offset}, -sm path {offset} 

-segment path {offset} {length}, -sm path {offset} {length} 

-nnl 

-nl 

-lines 

-brief, -bf 



Not To Be Reproduced A-30 F21 



list external variables 



Name : iist_extemal_var iables 

The list_external_var iables command prints information about 
variables managed by the system for the user, including FORTRAN common 
and PL/I external static variables whose names do not contain dollar 
signs. The default information is the location and size of each 
specified variable. 

Usage 

list_external_var iables names {-control_args} 

where: 

1. names 

are names of external variables, separated by spaces. 

2. control_args 

can be chosen from the following: 

-unlabeled_common, -uc 

is the name for unlabeled {or blank) common. 

-long, -Ig 

prints how and when the variables were allocated. 

-all, -a 

prints information for each variable the svstem . is 
manag ing . 

-no_header, -nhe 

suppresses the header. 
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Name : list_temp_segments 

The list te-mp — segments command lists the segments currently in 
the temporary segment pool associated with the user's process. This 
pool is managed by the get^temp^segroents^ and release_temp_segments__ 
subroutines (described in the MPM Subroutines) . 

Usage 

list_temp_segments {names} {-control_arg} 

where: 

1. names 

is a list of names identifying the programs whose temp 
segments are to be listed. 

2. control arg 

Ts -all (or -a) to list all temporary segments. If the 
command is issued with no control argument, it lists only 
those temporary segments currently assigned to some 
program. 

Examples 

To list all the segments currently in the pool, type: 

! list_temp_segments -all 

5 Segments, 2 Free 

IBBSCdfghgffkkkl. temp. 0246 work 

IBBBCdffddfdffkl. temp. 0247 work 

iBBBCddffdfffhhh.temp.0253 (free) 

iBBBCdgdgfhfgfsf .temp. 02 54 (free) 

IBBBCvdvfgvdgvvv. temp. 0321 editor 

To list the segments currently in use, type: 

! list temp_ segments 

3 Segments 

IBBBCdfghgffkkkl. temp. 0246 work 
IBBBCdffddfdffkl. temp. 0247 work 
! SBBCvdvfgvdgvvv. temp. 0321 editor 
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To list segments used by the program named editor, type: 
1 list_temp_segments editor 
1 segment 
!BBBCvdvfgvdgvvv.temp.0321 editor 
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Name : page_trace, pgt 

The page trace command prints a recent history of page faults and 
other system events within the calling process. 

Usage 

page trace {N} {-control__args} 

where: 

1. N 

prints the last N system events (mostly page faults) 
recorded for the calling process. If N is not specified, 
then all the entries in the system trace list for the 
calling process are printed. Currently, there is room for 
approximately 350 entries in the system trace array. 

2. control_args 

can be chosen from the following: 

-from STR, -fm STR 

searched the trace array for a user marker matching STR. 
If one is found, printing begins with it; otherwise, 
printing begins with the first element in the array. 

-long, -lg 

prints full pathnames where appropriate. The default is 
to print only entrynames. 

-no_header, -nhe 

suppresses the header that names each column. The default 
is to print the header. 

-output switch swname, -os swname 

writes all output on the I/O switch named swname, which 
must already be attached and open for stream_output . The 
default is to write all output on the user_output I/O 
switch. 

-to STR 

stops printing if a user marker marching STR is found. 
The default is to print until the end of the array. If 
both -from and -to are specified, the from marker is 
assumed to occur before the to marker. 



Output 
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The first column of output describes the type of trace entry. An 
empty column indicates that the entry is for a page fault. The second 
column of output is the real time, in milliseconds, since the previous 
entry's event occurred. The third column (printed for page faults 
only) is the ring number in which the page fault occurred, ^he fourth 
column of output contains the page number for entries, where 
appropriate. The fifth column gives the segment number for entries, 
where appropriate. The last column is the entryname (or pathname) of 
the segment for entries, where appropriate. 

Notes 

Since it is possible for segment numbers to be reused within a 
process, and since only segment numbers (not entrynames or pathnames) 
are kept in the trace array, the entrynames and pathnames associated 
with a trace entry may be for previous uses of the segment numbers, 
not the latest ones. In fact, the entry and pathnames printed are the 
current ones appropriate for the given segment number. 

For completeness, events occurring while inside the supervisor 
are also listed in the trace. The interpretation of these events 
sometimes requires detailed knowledge of the system structure; in 
particular, they may depend on activities of other users. For many 
purposes, the user will find it appropriate to identify the points at 
which he enters and leaves the supervisor and ignore the events in 
between. 



Typically, any single invocation of a program does not induce a 
page fault on every page touched by the program, since some pages may 
still be in primary memory from previous uses or use by another 
process. It may be necessary to obtain several traces to fully 
identify the extent of pages used. 

A count value (N) and either the -from or -to control argument 
cannot be specified in the same invocation of the page trace command. 
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Name : pr int_bind_map 

The print_bind map command displays all or part of the bind map 
of an object segment generated by version number 4 or subsequent 
versions of the binder. 

Usage 

print_bind_map path {components} {-control_args} 

where: 

1. path 

is the pathname of a bound object segment. 

2. components 

are the optional names of one or more components of this 
bound object and/or the bindfile name. Only the lines 
corresponding to these components are displayed. A 
component name must contain one or more nonnumeric 
characters. If it is purely numerical, it is assumed to 
be an octal offset within the bound segment and the lines 
corresponding to the component residing at that offset are 
displayed. A numerical component name can be specified by 
preceding it with the -name control argument (see below). 
If no component names are specified, the entire bind map 
is displayed. 

3. control args 

may be chosen from the following list: 

-long, -lg 

prints the components' relocation values (also printed in 
the default brief mode) , compilation times, and source 
languages. 

-name STR, -nm STR 

is used to indicate that STR is really a component name, 
even though it appears to be an octal offset. 

-no_header, -nhe 

omits all headers, printing only lines concerning the 
components themselves. 
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Name : print__link_info , pli 

The print^iink info command prints selected items of information 
for the specifTed object segments. 

Usage 

print_link_info paths {-control args} 

where : 

1. paths 

are the pathnames of object segments. 

2. control args 

can be chosen from the following list. (See "Note" 
below.) 

-length, -In 

print only the lengths of the sections in pathi. 

-entry, -et 

print only a listing of the path_i external definitions, 
giving their symbolic names and their relative addresses 

Wlufi-.ii unS sc^iucHui 
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-link, -Ik 

n»"i nf- 

external symbols referenced by path_i. 

-long 

prints more information when the header is printed. 
Additional information includes a listing of source 
programs used to generate the object segment, the contents 
of the "comment" field of the symbol header {often 
containing compiler options), and any unusual values in 
the symbol header. 

-header, -he 

prints the header (The header is not printed by default, 
if the -length, -entry, or -link control argument is 
specified, ) 

-no_header 

suppresses printing of the header. 

Note 

Control arguments can appear anywhere on the command line and 
apply to all pathnames. 
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Example 

I print_link_info program -long -length 

program 07/30/76 1554.2 edt Fri 

Object Segment >udd>Work>Wilson>program 

Created on 07/30/76 0010.1 edt Fri 

by Wilson. Work. a 

using Experimental PL/I Compiler of Thursday, July 26, 1976 at 21:38 

Translator: PL/I 

Comment: map table optimize 

Source: 
07/30/76 0010.1 edt Fri >user_dir dir>work>Wilson>s>s>program.pll 
12/15/75 1338.1 edt Mon > library_'Hir_dir>include>linkdcl . incl .pll 
06/30/75 1657.7 edt Mon >library_dir_dir> include>obj ect_info . incl .pll 
10/06/72 1206.8 edt Fri >library_dir_dir>include>source_map. incl .oil 
05/18/72 1512.4 edt Thu >library_dir_dir> include>symbol_block . incl .pll 
01/17/73 1551.4 edt Wed > library_dir_dir> include>pll_symbol__block. incl .pll 

Attributes: relocatable, procedure , standard 

Object Text Defs Link Symb Static 

Start 3450 3620 3656 3630 

Length 11110 3450 150 36 5215 



<ready> 



Also printed is: 

Severity, if it is nonzero. 
Entrybound, if it is nonzero. 
Text Boundary, if it is not 2. 
Static Boundary, if it is not 2. 
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Name : pr int_linkage_usage , pla 

The pr int_linkage_usage command lists the locations and size of 
linkage and static sections allocated for the current ring. This 
information is useful for debugging purposes or for analysis of how a 
process uses its linkage segments. 

A linkage section is associated with every procedure segment and 
every data segment that has definitions. 

Usage 

pr in t_l in kage_usag e 

Note 

For standard procedure segments, the information printed includes 
the name of the segment, its segment number, the offset of its linkage 
section, and the size (in words) of both its linkage section and its 
internal static storage. 
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Name ; probe, pb 

The probe command provides symbolic, interactive debugging 
facilities for programs compiled with PL/I, FORTRAN, or 'COBOL. Its 
features permit a user to interrupt a running program at a particular 
statement, examine and modify program variables in their initial state 
or during execution, examine the stack of block invocations, and list 
portions of the source program. External subroutines and functions 
may be invoked, with arguments as required, for execution under probe 
control. The probe command may be called recursively. 

Usage 

probe { procedure_name} 

where procedure_name is an optional argument that gives the symbolic 
name of an entry to the procedure or subroutine that is to be examined 
with probe. It can take the form ref erence_nameSof f set name. If no 
procedure_name argument is specified, the procedure owning the frame 
in which the last condition was raised is assumed, if o,ne exists; 
otherwise, an error is reported. 

Overview of Processing 

The probe command is generally used to examine an active program 
at points where execution has been suspended by one of the following: 

1. Breakpoint. Execution is temporarily halted at a point 
selected by the user and probe entered directly. Debugging 
requests associated with the breakpoint are automatically 
carried out and/or requests issued from the user's terminal. 
Program execution can be resumed at the point of 
interruption. 

2. Error. An error such as zerodivide or subscriptrange can 
interrupt program execution. After an error message is 
printed, a new command level is established. The user can 
then call probe to examine the state of the program. 

3. Quit signal. A run-away or looping program can be stopped 
by issuing a quit signal. A new command level is 
established and the user can call probe to determine the 
source of the problem. 

In all of these cases, variables of all storage classes 
(including automatic) are accessible. 
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The probe command can also be used to examine a nonactive program 
— one that has never been run or that has completed execution — by 
specifying a procedure_name argument in the command line. In this 
case, the user can examine static variables and the program source. 
However, the most common use is to set breaks before actually running 
the program. 

A program to be debugged with probe must have a standard symbol 
table that contains information about variables defined in the program 
and a statement map that gives the correspondence between source 
statements and object code. A symbol table and statement map are 
produced for the languages supported if the -table control argument is 
given at compilation. (A program may also be compiled with the 
-brief_table control argument, which produces only a statement map. 
The variables of a program compiled in this way cannot be examined 
with probe; however, the user may retrieve information about source 
statements and where the program was interrupted and also may set 
breakpoints at particular statements.) 

Information about programs being debugged is stored by probe in a 
segment in the user's home directory called Person_id .probe where 
Person_id is the user's log-in name. This segment is created 
automatically when needed. 

Probe Pointers 

Three internal "pointers" are used by probe to keep track of the 
program's state. They are: 

source pointer indicates the current source-program statement 
block pointer indicates the current block 

control pointer indicates the current control point 

These values are affected by certain probe requests. A user can, 
for example, position the source pointer to a particular statement, 
then list a portion of the source program beginning at that point. 

The block pointer serves two purposes. It identifies the 
procedure, subprogram, or begin block whose variables are to be 
examined. Further, it specifies the stack frame associated with the 
block and is used to distinguish among different occurrences of an 
automatic variable in a recursively invoked procedure. The control 
pointer marks the point at which a program is suspended. 

The initial values of these pointers are determined as described 
below. If a procedure name argument is given in the command line and 
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if the designated program is active, the control and source pointers 
are set to the last statement executed, and the block pointer is set 
to the most recent invocation of the procedure. If the designated 
program is not active, then the control and source pointers are set to 
the entry statement, and the block pointer to the outermost block (but 
with no active frame) . 

If no procedure name argument is given and the default rule 
applies (i.e., a condition has been raised), then the procedure in 
which the condition was raised is used. The source and control 
pointers are set to the statement where the condition was raised, and 
the block pointer to the block containing that statement. 

Similarly, when probe is entered because of a breakpoint 
encountered during the execution of a program, the source and control 
pointers are set to the statement at which the break has been set; and 
the block pointer to the block containing that statement. 

Breakpoints 

A breakpoint causes a temporary interruption of program 
execution, during which debugging operations can be performed. Using 
probe requests, a user can set a' breakpoint before or after any 
statement and can associate a list of probe requests with the break. 
A break set after a statement may, in some cases, not be executed due 
to the nature of the code generated for that statement. When the 
break is encountered during execution, probe is entered and the list 
of requests interpreted automatically. These requests might, for 
example, display the value of a -variable or alter its value 
(effectively allowing source level patching of the program), tell what 
line was just executed, or cause probe to read a list of requests from 
the terminal to permit the user to interactively examine the state of 
his program. When the request list associated with the break is 
exhausted, the execution of the program is resumed from the point at 
which it was interrupted. 

The implementation of a breakpoint by probe consists of patching 
a call to the probe command into the appropriate location in the 
object segment of the program. As a result, there need not be an 
active invocation of probe for a break to occur; also, breakpoints may 
be set in a program before it is run, while the program is suspended 
by another break, or before a program interrupted by a quit signal or 
error condition has been restarted. 
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Probe Requests 

A probe request consists of a keyword (or its abbreviation) that 
specifies the desired function and any arguments required by the 
particular request. 

A series of requests may be given in the form of a request list. 
Here, individual requests are separated by semicolons or newline 
characters. 

A single request or a parenthesized request list may be preceded 
by a conditional predicate whose value determines if and when the 
requests it modifies will be executed. 

The following pages present the format and function of each probe 
request. Requests are grouped according to function. Required 
arguments are indicated for each. The syntax and semantics of generic 
arguments such as expressions, procedures, labels, and variables are 
defined under separate headings following the request descriptions. 

The following descriptions first give the name of the request and 
its abbreviated form (if any) . This line is followed by the general 
format line(s) of the' request. 



BASIC REQUESTS 

1. value, v 

value expression 
value cross-section 



The request "value expression" causes the value of the given 
expression to be displayed. Allowable expressions are variables, 
builtin functions such as addr and octal, and the value returned by an 
external function. The evaluation of expressions is described later 
(following the descriptions of all the requests) under "Evaluation of 
Expressions." 
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Examples: 

value var 

value p -> a.b( j) .c 
value addr (i) 
value octal (ptr) 
value function (2) 

The request "value cross-section" is used to display values 
contained in a cross-section of an array. A cross-section is 
specified by giving the upper and lower bounds of one or more 
subscripts, as in: 

value array (1:5, 1) 

The notation 1:5 indicates the range one through five for the 
first subscript. The example above prints array(l,l), array(2,l), 
..., array(5,l). More than one dimension can be iterated; for 
instance, array' 1 : 2, 1: 2) prints, in order, array(l,l), array(l,2), 
array(2,l), array(2,2). 

2. let, 1 

let variable = expression 

let cross-section = expression 

This request sets the specified variable or array elements to the 
value of the expression. If the variable and the expression are of 
different data type-5, conversion is performed according to the rules 
of PL/I. Array cross-sections are expressed as shown in the value 
request above. One array cross-section may not be assigned to 
another. 

Examples : 

let var = 2 

let array (2,3) = i + 1 
let p -> a.b(l:2).c = 10b 
let ptr = null 

Because of compiler optimization, the change may not take 
immediate effect in the program, though the value request shows the 
value to be altered. 
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call procedure (argl, ..., argn) 



This request calls the procedure named with the arguments given. 
If the procedure expects arguments of a certain type, those given are 
converted to the expected type; otherwise, they are passed without 
conversion. The value request (see above) can be used to invoke a 
function, with the same sort of argument conversion taking place. If 
the procedure has no arguments, a null argument list, "()", must be 
given. 



Examples; 



call sub ("abc", p -> p2 -> bv, 25o, addr(j)) 

call sub_noargs () 
value function ("010"b) 



4. goto, g 

goto label 



This request transfers control from probe to 
specified and initiates program execution at that point, 



the s ': .i tern en t 



Examples : 



goto label_var 
goto action (3) 
goto 29 

goto $110 

goto $c,l 



:o value of label variable 
:o label constant 



line 2y oi 



transfer 

transfer 

transfer to statement on 

current program 

transfer to line with label 110 in the 

FORTRAN program 

transfer to the statement following the 

current statement 



Because of compiler optimization, unpredictable results may occur 
when using this request. 



5 . qu i t , q 
qui t 



This request causes a return to command level 
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6 . continue, c 
continue 



This request restarts a program that has been suspended by a 
break. If this request is issued in any other context, probe-returns 
to its caller (generally command level) . 



SOURCE REQUESTS 
1. source, sc 
source n 



This request displays one or more statements beginning with the 
current statement (i.e., the source pointer). If n is not specified, 
one line is printed? otherwise, n lines are printed. Only executable 
statements for which code has been generated can be listed; however, 
if a range of statements is requested, intervening text, such as 
comments and nonexecutable statements (for example, declarations), is 
included in the output. 



position, ps 

position label 
position + n 



This request sets the source pointer to the statement indicated 

by label or to an executable statement relative to the current 
statement as indicated by the value of n and displays it if the user 

is in long mode. If +n is given, the pointer is sat forward n 

statements; if -n is given, the pointer is set back n statements. If 

no label or offset is given, the statement designated by the control 
pointer is assumed. 



Examples : 

position here 

position action (3) 
position 2-14 

position +2 
position -5 



set the source ptr to the statement 

labeled here 

to the statement labeled action (3) 

to the statement on line 14 of include 

file 2 of the program 

move forward two statements in the 

source 

move back five statements 
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The position request can also be used to search for an executable 
statement that contains a specified string, using the form: 



position "string" 



The search begins with the statement following the current 
statement and continues through the program, if necessary, until the 
current statement is again reached. If a match is found, the source 
pointer is set to that statement. If the specified string contains a 
quotation mark, it must be doubled when given in the request line. 
Because statements are reordered by the compiler, the search may not 
necessarily find statements in the same order as the source listing of 
the program would indicate. 



Examples : 



position "write (6,10)' 

position "str = ""a" 

position "q+2"; source 
SYMBOL REQUESTS 



locate the statement in the program 

locate str = "a 

locate and print the statement 



stack, sk 






This request traces the stack backward beginning at the ith frame 
and continuing for n frames. If i is not given, then the trace begins 
with the most recent frame and continues for n frames. If no limits 
are given, the entire stack is traced. The trace lists ail active 
procedures and block invocations (including quick blocks) beginning 
with the most recent. For each block, a frame or level number is 
given, as is the name of any conditions raised in the frame. 



Examples : 



stack 
stack 2 
stack 3, 2 



trace the whole stack 

trace the two most recent frames 

trace the third and second frames 



Normally, system or subsystem support procedures are not included 
in the stack trace. These may be included by specifying "all". 



Examples: 

stack all 



trace the whole stack including all 
support stack frames 
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stack 5,3 all 



trace 
frames 
f ram as 



the fifth, 
includ ing 



fourth, and third 
all support stack 



2. use, u 

use block 



This request selects the block to be used for subsequent probe 
requests. It may be specified by the name of an entry, a label, or a 
stack frame number (level i) . If no block is specified, then the 
block originally used {when probe was entered) is assumed. The block 
pointer is set to the specified block so that variables in that block 
can be referenced. In addition, the source pointer is set to the last 
statement executed in the block. In this way, the point at which the 
block exited can be found through use of the source request. 
Acceptable block specifications include: 



procedure name 

label 
level i 
-n 



In this context, procedure_name is the name of a procedure or 
subprogram entry point whose frame is desired; its usage is 
essentially the same as if used on the command line. A label denotes 
the block that contains the statement identified by the label or line 
number; for instance, the label on a begin statement denotes that 
begin block. If the label's block is not active, the source pointer 
is set to the statement specified. The block specification level i 
uses the block with level number i from a stack trace; -n uses the nth 
previous instance of the current block, allowing one to move back to a 
previous recursion level. If more frames are requested than actually 
exist, the last one found is used. 



Examples : 

use sub 

use label 

use level 2 
use -1 

use -999 



use the block that 
occupies 

use the block that 
statement labeled label 
use the second frame in 
use the previous 
current block 
use the 



procedure sub 
contains the 

the stack trace 
instance of the 



st { Oxu est ) 



instance 
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When 
procedures 

requested. 



a level is specified, the last trace mode (support 
included or excluded) specified is used to find the level 



3. symbol, sb 

symbol identifier 



This request displays the attributes of the variable specified 
and the name of the block in which its declaration is found. If the 
size or dimensions of the variable are not constant, an attempt is 
made to evaluate the size or extent expression; if the value is not 
available, an asterisk (*) is used instead. 



4. where, wh 

where source 

where block 

where control 



This request displays the current value. of one or all of the 
pointers. Source and control give the statement number of the 
corresponding statement. Block gives the name of the block currently 
being used; if the block is active, its level number is also given. 
If neither source, block, or control appears, the information for all 
three is given. 



Examples : 



wh ere 

where source 



give the value of all 
give the value of the 



three pointers 
source pointer 



3REAK REQUESTS 

I. before, b 

before label: 
before label: 



request 
(request list) 



This request sets a breakpoint before the statement specified by 
label and causes the given request(s) to be associated with the break. 
If no label is given, the current statement is assumed. If no 
requests are given, a halt is assumed (see the halt request described 
below) . 
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When 
probe is 

requests 
execution 



the running program arrives at the statement specified, 

entered before the statement is executed, and associated 

are processed automatically. When all requests are done, 

of the program resumes at the statement before which the 



break was set. A breakpoint set before a statement takes effect 
whether the statement is arrived at in sequence or as the result of a 
branch or call from some other location. 



Examples; 



before? (value var- value var?.l 



before quick: 
before 



value x 



set a break before the current 

statement to display the value of 

the variables var and var2 

set a break before the statement 

labeled quick 

set a break containing the halt 

request before the current 

statement 



The request list may extend across line boundaries if necessary, 



2. after, a 



after label : 
after label : 



request 
(request list) 



This request is the same as the before request except that 
break is set after the designated statement. This means that 
request list is interpreted after the statement has been 
the statement branches to another location in the 



executed 
program , 



breakpoint does not take effect; also, in some cases, the break 
not be executed due to the nature of the code generated for 
statement. 



the 
the 
If 
the 
may 
the 



Notice the distinction between two breakpoints in sequence 
one that is after statement x is not « 
to statement x+1 from elsewhere. The 

take place. 



The 

.ve when control is passed 

break before statement x+I does 
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3. halt, h 
halt 



This request causes probe to stop processing its current input 
and to read requests from the terminal. A new invocation of probe is 
created with new pointers set to the values at the time the halt 
request was executed. As part of a break request list, it enables the 
user to enter requests while a program is suspended by the break. A 
running program can be halted in this way." A subsequent continue 
request causes probe to resume what it was doing before it stopped; 
for example, finish a break request list and resume execution of the 
prog ram . 



Examples: 



before 29: halt 



after: (value a; halt; value b) 



program to 
and allows 



halt at 



causes the 

statement 29 and allows the user 
to enter probe requests (the 
continue request can be used to 
restart the program) 



causes 
printed 
halts; 
enters a 

,f 



the value of 
before the 
later, after 



a to be 

program 

the user 



continue request, the 
value of b is printed, and the 
execution of the nroaram is 
resumed 



4. 



reset, r 



reset 

reset at/after/before label 

reset procedure 

reset * 



This reques 
When no argument 

label argument, breaks set before 
deleted; with a procedure or asterisk 



deletes breaks set by the before and after requests. 
s supplied, reset deletes the current break 

a 
all 



a specified 
■be deleted. 



and/or after 
(*) argument, 



statement are 
the breaks in 



segment or all breaks in all segments, respectively, can 
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Examples: 



reset 

reset at 34 

reset after 3< 
reset sub 
reset * 



delete the current break 

delete breaks set before and after the 

first statement on line 34 

delete the break set after line 34 

delete all breaks in sub 

delete all known breaks 



status, st 

status 

status at/after/before label 

status procedure 

status * 



This request gives information about breaks that have been set by 
the user. The scope of the requests is similar to reset except that 
status without arguments specifies all breaks in the current program 
(the program containing the statement designated by the source 
pointer) . 



Examples: 

status 

status before label 

status sub 
status * 



list the breaks set in the current 

prog ram 
give the break set before the statement 

at label 
list the breaks set in sub 
list the procedures that have breaks 

set in them 



6. pause, pa 
pause 



list. 



This request is equivalent to "halt; reset" in a break request 
It causes the procedure to execute a break once and then reset 



it. If the statement after which the break is set transfers 
elsewhere, the break does not occur and remains set until encountered 
sometime in the future or explicitly reset at some other point. 
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7. step, s 
step 

This request enables the user to step through his program one 
statement at a time. It sets a break consisting of a pause request 
after the next statement to be executed (as indicated by the control 
pointer) and resumes the execution of the program as with a continue 
request. 

MISCELLANEOUS REQUESTS 

1. mode 

mode brief 
mode long 

This request turns the brief message mode on or off. In brief 
mode, most messages generated by probe are shortened and others are 
suppressed altogether. The default is long. 

2. execute, e 
execute "string" 

This request passes one or more Multics command lines, 
represented above by "string", to the command processor for execution. 

3. acknowledge 



This request causes probe to identify itself by printing "probe" 
on the terminal. It may be used, for example, to determine if a 
called procedure has returned. 
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CONDITIONAL PREDICATES 

1. if 

if conditional expression: request 

if conditional expression: (request list) 

The request or request list is executed if the conditional 
expression is true. The expression must be of the form: 

expression operator expression 

where operator can be <= , <, =, "=, >, or >=. 

Example : 

if a < b: let p = addr (a) 

This predicate is most useful in a break request list where it 
can be used to cause a conditional halt. For example, 

before: if z ~= "10"b: halt 

causes the program to stop only when z "- "10"b. 

2. while, wl 

while conditional expression: request 

while conditional expression: (request list) 

The request or request list is executed repeatedly as long as the 
conditional expression is true. 

Example : 

while p'~= null: (value p -> r.val; let p = p -> r.next) 
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Evaluation o£ Expressions 

Allowable expressions include simple scalar variables, constants, 

and probe builtin functions. The sum and difference of computational 

(arithmetic and string) values can also be used. 

Variables can be simple identifiers, subscripted references, 

structure qualified references, and locator qualified references. 

Subscripts are also expressions. Locators must be offsets, pointer 
variables, or constants. 



Examples: 



running_total 
salaries (p -> 
a.b(2) ,c(3) 
a.b.c(2,3) 
x.y -> var 



i - 2) 



Constants can 
Arithmetic constants 



be arithmetic, 
can be either 



s t r i ng , 
decimal 



bit, and 
or binary. 



po inter 
fixed or 



floating point, real or complex. Also, octal numbers are permitted as 
abbreviations for binary integers (e.g., 12o =10). 



Examples : 



-123 

10b 

45.37 

4.73el0 

2.1-0.3i 

12345670O 



Character and bit strings without repetition factors are allowed. 
Character strings can include newline characters. Octal strings can 
be used in place of bit strings (e.g., "123"o = "001010011 "b) . 



Examples: 

"abc" 

"quote" "inst ring" 

"1010"b 
"01234567"o 
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A pointer constant is of the form: 

segment_n umber I word__of f set (bit_of f set) 

where the segment_number and word_offset must be in octal. The 
bit_offset is optional but if given must be in decimal. The pointer 
constant can be used as a locator. 



^xam 1 ^! es : 

21415764 
23217413(9) 

Four builtin functions are provided by probe: addr, null, octal, 
and substr. The function of addr and null is the same as in PL/I: 
addr takes one argument and returns a pointer to its argument; null, 
taking no arguments, returns a null pointer. The function octal acts 
very much like the PL/I unspec builtin function in that it treats its 
argument as a bit string of the same length as the raw data value and 
can be used in a similar manner as a pseudo-variable. However, when 
used in the value request, the value is displayed in octal. Data 
items not occupying a multiple of three bits are padded on the right. 
The substr builtin function may be used as a function or 
pseudo-variable. It takes two or three arguments. The first argument 
must be a character or bit string or a reference to the octal builtin. 
function; the second and optional third arguments give the offset and 
length of the desired substring as with the PL/I substr builtin 
function. 



Note 

These builtin functions cannot be used if a program variable of 
the same name appears in the block being referenced. (For example, if 
x and octal are arrays in the same block, then octal (x(2)) becomes a 
reference to the variable octal, not the probe builtin). 
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Examples : 

For the following examples, assume that p is declared as an 
aligned pointer, i as fixed binary initial(-2), and cs as character(8) 
initial ( "abcdefgh" ) . 

value addr (i) displays the address of i 

let p = null sets the pointer, p, to null 

value octal (i) displays the storage containing i in 

octal, giving: 777777777776 

value substr (cs, 2, 3) displays "bed" 

let substr (cs, 4, 1)="" sets cs to "abc fgh" 

Label References 

A label identifies a source program statement and can be a label 
variable or constant, a line number in source-listing format, or one 
of the following special statement designators: 

$c designates the "current statement" 

$b designates the statement on which the most recent break. 

occurred 

$number designates a FORTRAN label 

An optional offset of the form " ,_s" is also allowed. 

Examples: 

label statement at label 

label__var statement to which label_var is set 

17 statement on line 17 of program 

3-14,2 statement 2 on line 14 of include file 

3 

$b statement at which last break occurred 

$c,l statement after current statement 

$100 FORTRAN statement labeled 100 

Generally, a label can also be the name of a procedure, entry, or 
subroutine statement. 



Procedure References 
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A procedure_name is an identifier representing an entry variable 
or constant. External reference names, representing entry points not 
declared in the current block, can be used. 



Evaluation of Variable References 

When a variable is referenced 
to evaluate it by checking for 
current block and, if necessary, in its parents. 
found, the list of builtin functions is searched 
context 3j.j.ows a proceuure name, 
search rules. 



in a request, probe first attempts 

an applicable declaration in the 

If no declaration is 

Finally, when the 

L W J. , ± W W i A i^ U11C \_1 *J <= i_ -J 



The block in which a variable reference is resolved can be 
altered by the use request that sets the current block. For example, 
if "value var" displays the value of var in the current block, then 
"use -1; value var" displays the value of var at the previous level of 
recursion. An optional block specification is available for 
referencing variables in other blocks: 



variable [block] 



where block is the same as in the use request, 
this manner does not alter the block pointer. 



The use of blocks in 



Examples: 



var[-l] 

abc [other_block] 

xyz[39] 

n.m[ level 4] 
q(2) [sub] 



looks for the previous value of var 

looks in "other_block n for abc 

looks in the block that contains line 

39 for xyz 
looks in the block at level 4 for n.m 
looks in the procedure sub for q(2) 



A block specification can be used to qualify a variable reference 
in any context the variable could be used. However, a block 
specification on a label or entry constant is ignored unless the 
relative (-n) format is used and the label or entry is itself used in 
a block specification. In such a case, it is taken to mean the nth 
previous instance of the block designated by the label or entry; that 
is, "var[sub[-2] ] " references var in the second previous invocation 
(third on the stack) of sub. 
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Sample Debugging Sessions 

Two extensive examples are given on the following pages to 
illustrate both how probe requests are used and how to get useful 
debugging information out of them. the first example was devised 
principally to demonstrate the application of probe requests. A 
listing of the source of the program, test, is given on the next page. 
The program has been compiled with the -table control argument (line 
1) . The sample output follows with an exclamation point (!) denoting 
lines typed by the user. Unless otherwise indicated, line numbers 
referenced in the following paragraphs are from the sample output. 

The user first calls his program (line 5); noticing that it seems 
to be looping, he stops it by issuing the quit signal (line 6). After 
the user invokes probe (line 10), it responds by telling him that the 
internal function fun was executing line 38 when interrupted. Since 
the source pointer was automatically set to that line," the source 
request (line 12) causes the current source statement to be displayed. 
A statement causing an error could be displayed in a similar manner. 

1 test: procedure; 

2 

3 declare. 

4 

5 (i, j) fixed binary, 

6 Is structure based ( p) , 

7 2 num fixed binary, 

3 h fn rofsr fc nirnil 1 flnaf hinarti 

9 p pointer, n fixed binary, 

10 sysprint file; 

11 
12 

13 n = 5; 

14 allocate s set ( p) ; 
15 

16 do i = 1 to s. num; 

17 s.b(i) = fun (i, 1) ; 

18 end; 

19 put skip list (s.b); 
20 

21 do j = s.num to 1 by -1; 

22 s.b( j) = fun (-j , -1) ; 

23 end; 

24 put skip list(s.b); 
25 

26 return; 

27 

28 

29 fun: procedure (b, i) returns (float binary); 

30 

31 declare 
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32 
33 

34 
35 
36 
37 
38 
39 
40 
41 
42 



(b r i) fixed binary; 

if b = 

then return (1) ; 
else do; 

b = b - i; 

return- (2**b + fun (b, i)); 
end; 



end fun; 
44 end test; 
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j. 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 



! pll test -table 
PL/I 
r 1248 3.211 28.336 280 

! test 
i (quit) 

QUIT 

r 1250 5.371 6.702 52 level 2, 10 



probe 

Condition quit raised at line 38 of fun. 

source 

return (2**b + fun (b, i) ) ; 



stack 
11 
10 

9 

8 

7 

5 

5 

4 

3 
2 



command_processo r_ 

release_stack 

unclaimed_signai 

real_sdh_ 

return_to_r ing_0_ 

fun 

test 

command_processo r_ 

listen 



process_overseer_ 
user_init_admin_ 

! . use level 5 

i source 

s.b( i) = fun ( i , 1) ; 

i value s.num 



qui t 



31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 



! position "i = 1"; source 

do i = 1 to s.num; 
1 after: value i 

Break set after line 16 of test. 
I quit 

r 1252 1.375 16.394 354 level 2, 10 

! release 

r 1252 .126 .922 19 



test 



i (quit) 



1 

1 
1 

1 



QUIT 

r 1252 3.069 .650 25 level 2, 12 

release 

r 1253 ,092 .937 20 



1 probe test 
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54 


I status 


55 


Break after line 16. 


56 


! status after 16 


57 


Break after line 16: value i 


58 


! reset at 16 


59 


Break reset after line 16 of test. 


60 


i position 34 


61 


i source 


62 


if b = 


63 


then return (1) ; 


64 


! before: halt 


65 


Broat cot- hdfnris 1 ina "3 A of 1-PSt-. 


66 


1 quit 


67 


r 1255 .781 12.356 333 


68 




69 


! test 


70 


Stopped before line 34 of fun. 


71 


1 value b 


72 


1 


73 


1 where 


74 


Current line is line 34 of test; 


75 


Using level 6: fun. 


76 


Control at line 34 of fun. 


77 


I value i 


78 


1 


79 


! c 


80 


Stopped before line 34 of fun. 


81 


! stack 5 


82 


8 break 


33 


7 fun 


84 


6 fun 


35 


5 test' 


36 


4 command_processor_ 


87 


I value b 


38 





89 


' value b[-l] 


90 





91 


! value i 


92 


1 


93 


! symbol i 


94 


fixed binary{17,0) aligned parameter 


95 


Declared in fun. 


96 


! use test 


97 


! value i 


98 





99 


! reset 


100 


Break reset before line 34 of test. 


101 


! quit 


102 


r 1307 4.870 64.783 1544 



The stack command is then used (line 14) to see in what order the 
procedures were called. The output shows that procedure test was 
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called from command level, and then called fun. While fun was 
executing, a quit signal was issued and established a new command 
level. 

The use request (line 26) sets the block pointer to the outermost 
block of procedure test, and the source pointer to the last statement 
executed in that block — the statement which invoked uhe function 
fun. 



The source request (line 27) is issued to display the current 
statement (as set above) to determine from which line of the program 
(17 or 27) fun was actually invoked.. 

Since the block pointer has also been set, the user can check the 
value of "s.num" with the value request (line 28) and ascertain that 
it is as desired. Since there is no new declaration of "s.num" within 
the procedure fun, the declaration made in the parent block, test, is 
known and the value of "s.num" could be displayed without changing the 
block pointer as would be necessary if there were a conflicting 
declaration. 

The user decides that it is worthwhile to trace the value of i. 
Rather than recompiling his program with a "put statement' added in a 
strategic location, probe allows him to set a break containing a value 
request to accomplish the same thing. The user wants to set the break 
after the do statement on line 16 of the program and searches for it 
with the position request (line 31). The source request is used to 
verify that the correct line was found. The after request is used to 
actually set the break (line 33). The quit request (line 35) then 
causes probe to return command level. 

To abort the suspended program test, the user invokes the Multics 
release command (line 38). If he had done this just after issuing the 
quit signal, he could not have used probe to examine automatic 
variables inside the program or to determine where the program had 
been interrupted. 



The program is restarted (line 41) but now, after each execution 
of line 16, the break occurs and probe displays the value of i. 
Clearly, it is not being incremented as it should. Since this 
approach is not producing any useful information, the user aborts the 
program and tries to delete the break. The status request is used to 
tell what breaks have been set in the procedure test (line 54), and 
then (line 56) to see the probe request associated with that break. 
The break is then deleted with the reset request (line 58). If there 
had also been a "Break before 16", then the request "reset at 15" 
would have deleted both. 
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The user next decides to examine fun, so he sets a break that 
will halt every time fun is invoked (lines 60 through 64). Looking at 
the listing, he sees that the first statement in fun is on line 34, so 
he sets the source pointer to that statement with the position request 
and sets a break to halt the program. To accomplish the same thing, 
"before 34: halt" could have been used. 

The program is called (line 69) and then halts when the break 
before line 34 is reached. The user displays b and i (lines 71 and 
77), getting the values he expected. The where request is also used 

/i;__ TIN J- — *m U — _ 1- * — j_ 1~ * — .»—,.. — ,-*. ~ j. -* *. A -. C j_ U * « ~* ,-. mU .-* /-« An faiMiiA 

ixxue / j; tu i-ueuis. uu unc i-uttcuu oi_aue u j. uiiiuya. me guiiuiuus 

request (line 79) restarts fun, which calls itself recursively and 
stops again. The stack request (line 81, showing the last five 
frames) verifies that fact. The user displays the b in the current 
instance of fun (line 87, at level 7) and in the previous one (line 
89, at level 6). Mistakenly expecting the b's at different levels to 
be different, he gets suspicious. The variable i has the value 
expected (line 91), but the symbol command (line 93) shows that it is 
the wrong instance of i — the parameter to fun, not the loop index. 
To get the correct instance, he must look in the frame belonging to 
the procedure test (line 96) and display that i (line 97). This i has 
been set to 0. The user then realizes his error. The function is 
modifying its argument (the loop index i) on line 37 (line 94). When 
the user has finished debugging the program> the reset request (line 
99) is used to delete the currently active break (the one that just 
occurred), and the- program is aborted with the quit request (line 
101) . 

The preceding example was constructed to give a user a feeling 

for applying probe requests. The following example is taken from an 

actual debugging session using probe and illustrates several 
additional techniques available to the user. 

The program of interest is a subroutine, sort_strings , that is 
supposed to sort a character array of arbitrary dimension; the array 
is passed as an argument to the subroutine. Since very large strings 
are being compared, it would be time consuming to exchange the strings 
themselves. Therefore, an array of pointers to the strings (actually, 
the indices of the strings in the original array) is first sorted by a 
simple bubble sort, and the strings moved afterwards into the correct 
order. There are (at least) two bugs in the program as it appears in 
the listing. The next two paragraphs further describe the algorithm 
intended . 

A bubble sort involves making repeated passes over an input 
array, comparing adjacent pairs of values, and interchanging them as 
necessary. This moves the larger (smaller) values toward the end of 
the array. The sort only covers that portion of the array that is out 
of order (i.e., up to the element where the final exchange took place 
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on the previous pass — all elements following this point are clearly 
correctly arranged). The example below illustrates how a bubble sort 
wor<s in one case. (The hyphen delimits the end of the search.) 

Original First Pass Second Pass Third Pass 



a 
a 
c 
b 
e 



-> 



a 
c 
b 



-> 



a 
b 

c 
d 

e 



-> 



a 
b 
c 
d 
e 



In the sort_strings subroutine (see source listing below) , "k" 
determines the last element of the array needing to be sorted. 
Soring continues until no exchanges occurred during the last oass 
(i.e., until the test, k <= 1, fails). Th« " " " 
indices that are actually sorted. 



le "order" array contains" the 



The reordering method used is to scan for unordered items and 
.nen move the entire chain (a replaces b; b replaces c ; and c replac 
a) containing the element. For example: 



es 



Initial Ordering Desired Ordering 



1 
2 
3 

4 
5 



e 
d 
a 
b 
c 



3 

4 
5 
2 

1 



D 
C 

d 
e 



Movements 



L. GUI M X 



1 <- 3 (a) 2 <- 4 (b) 
3 <- 5 (c) 4 <- temp 
5 <- temp 



All elements that have been moved into the correct locatio 
flagged as naving been moved by setting their order values to -1. 



on are 



Source listings of the program and subroutine, named testss and 
soru_strings respectively, are given below. 



1 testss: procedure; 
2 



3 
4 
5 
6 
7 
3 



/* test caller for sort_strings */ 
declare 

i fixed binary, sysprint file, 

sort_strings entry ( character (256) varying dimension^ 

array (6) character (256 ) varying initial 
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10 ( "probe", "hello", "xray", "nice", "def" , "abc" 

11 
12 

13 call so rt — strings (array) ; 

14 do i = 1 to 6; 

15 put list (array ( i) ) ; 

16 put skip; 

17 end; 
18 

19 end testss; 



1 sort_strings: procedure (strings); 

2 

3 declare 

4 

5 strings character (256) varying dimension(*) , 

6 order fixed binary dimension (hbound (strings, 1)), 

7 temp character (256) varying, 

8 (i, k, 1, t) fixed binary; 
9 

10 

11 /* initialize order array */ 

12 

13 do i = 1 to hbound (order, 1) ; 

14 order (i) = i; 

15 end; 
16 

17 /* perform bubble sort */ 
18 

19 k, 1 = hbound (strings, 1) ; 

20 do while (k <= 1) ; 

21 do i = 2 to k; 

22 1 = i - 1; 

23 if strings (order (1)) > strings (order (i)) then 

24 t = order (1); order (1) = order (i); order (i 

25 k = 1; 

26 end; 

27 end; 

28 end ; 
29 

30 /* move strings into above ordering */ 
31 

32 do i = 1 to hbound (strings, 1); 

33 if order (i) *= -1 then do; 

34 temp = strings (i); 

35 

36 /* follow chain 'til reach start again */ 

37 

38 do k = i repeat 1 while (k ~= -1); 

39 1 = Order ( k) ; 

40 strings (k) = strings (1); 
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41 order (k) = -1 ; 

42 end; 

43 strings (1) = temp; 

44 end; 

45 end; 
46 

47 

48 end sort_strings; 

The debugging session begins below. Again, an exclamation point 
(i) indicates lines typed by the user. 

1 i testss 

2 ! (quit) 

3 QUIT 

4 r 736 6.068 0.132 9 level 2, 10 
5 

6 1 probe 

7 Condition quit raised at line 21 of sort strings. 

8 ! source 

9 do i = 2 to k; 

10 I value k 

11 1 

12 ! value 1 



First the program testss, used to test the sort_strings 
subroutine, is called from command level (line 1) . When no output is 
produced, the program is aborted by issuing a quit signal, and probe 
is invoked to determine where the program was looping (line 6). 

When probe is entered, it responds by giving the procedure and 
line where execution was interrupted. The source pointer is set by 
default to that line, so that the source request (line 3) may be used 
to display the text of the statement. The output does not indicate 
whether the infinite loop is occurring in the inner (do i = 2 to k) or 
outer (do while (k <- 1) ) loop. The value of k (line 11) is 1, which 
implies that the inner loop is not being entered; the value of 1 (line 
13) is also 1 explaining why the outer loop never terminates. 

An examination of the program shows that k and 1 could take on 
these values if elements 1 and 2 are exchanged on a pass with k = 2; 
on subsequent passes, no exchanges are made (as the inner loop is not 
entered) , and the termination condition is never met. What is needed 
is to force 1 to be less than k on all passes unless an exchange 
actually occurs. This can be done by setting 1 = -1 before attempting 
the inner loop. 

Not To 3e Reproduced A-67 F21 



probe, pb 



14 ! before: let 1 = -1 

15 Break set before line 21 of sort_stri ngs . 

16 ! quit 

17 r 737 1.217 3.562 97 level 2, 10 
18 

19 i start 
20 

21 def 

22 hello 

23 probe 

24 abc 

25 xray 

26 r 737 0.359 0.182 

The probe command can be used to modify the value of variables 
either interactively or as part of a break request list. In the 
latter case, the change is made every time the program is executed. A 
breakpoint is set before the current statement (line 21 of the program 
— the inner loop) to set the value of.l to -1 with the before request 
(line 14). The quit request (line 16) causes a return to command 
level, and the Multics start command (line 19) restarts the program 
from whe're it was interrupted. This time output is generated. 
However, the strings are not being sorted correctly. 

27 I probe sort_strings 

28 1 position "i = l";source 

29 do i = 1 to hbound (order, 1) ; 

30 ! position " i = l";source 

31 do i = 1 to hbound (strings , 1); 

32 i before 

33 Break set before line 32 of sort_strings . 

34 < quit 

35 r 738 0.218 0.002 14 
36 

37 1 testss 

38 Stopped before line 32 of so rt_strings . 

39 1 symbol order 

40 fixed binary(17,0) aligned automatic dimension(6) 

41 Declared in sort_strings. 

42 i value order(l:6) 

43 6 

44 5 

45 2 

46 4 

47 1 

48 3 

One way to determine whether it is the sorting or ordering 
section of the program that is functioning incorrectly, is to stop the 
program before the ordering section and look at its input, the array 

Not To Be Reproduced A-68 F21 



probe, pb 



The position request (line 28} is an attempt to locate the 
desired statement, but the source request (line 28), used to check 
that the correct line has been found, shows that the wrong one was 
found. The process is repeated (line 30), and the source pointer set 
to the correct line. A break is set (line 32) to cause the program to 
"halt" at that statement and enter probe, The driving program is 
begun once again (line 37), and sort_strings halts at the desired 
location. The symbol request (line 39) is used to check that the 
correct dimensions are being received for the array order. The value 
request (line 42) is used to display order(l), ..., order(6). It can 
be seen that these are the correct values ("abc", in position 6, is to 
be moved to position 1, etc.). 

49 ! position 39; source 

50 * 1 - order (k) 

51 1 after: (value k; value 1) 

52 Break set after line 39 of sort_strings. 

53 ! continue 

54 1 

55 5 

56 6 

57 3 

58 3 

59 2 

60 2 

c^ c 

62 5 

63 1 

64 1 

65 -1 

66 4 

67 4 

68 4 

69 -1 

70 nice 

71 def 

72 hello 

73 probe 
7 4 abc 

75 xray 

76 r 740 0.602 0.000 

It appears that the sorting code is working properly (with the 
patch in it). Therefore, the reordering of the array is failing for 
some other reason. The user then begins to trace the exchanges that 
are made. A break is set (lines 49 and 51) to display the values of k 
(the element to which the string is to be moved) and 1 (the element 
from which the string is to be moved) as the program is running. As 
stated previously, the effect of recompiling the program with a put 
statement added can be duplicated in this manner. The break is set 
after the line where both values have been determined for the 
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exchange. The 'continue request (line 53) restarts the program from 
where it was suspended by the break. 

The output shows that extra exchanges are taking place. When k = 
5, the next element on the chain is the first element (1 = 1), and the 
fifth element should therefore be replaced by the copy of the first 
value stored in "temp." It should not be replaced by the current 
first element (the old element 6, " abc" ) . Nor should the program 
continue to move the undefined element -1 into element 1. 

77 1 probe sort_strings 

78 ! reset at 39 

79 Break reset after line 39 of sort_strings . 

80 I before 39: if order(k) = i: ( 

81 ! let strings(k) = temp 

82 ! let order(k) = -1 

83 1 goto 42 

84 I - ) 

35 Break set before line 39 of sort_strings . 

86 ! emit 

87 r 742 0.280 0.966 56 

For the program to work properly, the movement through the chain 
must stop when the next element is the first (i.e., when order (k) = 
i) . The saved value of the first (temp) should then be copied into 
the current element (strings(k) ) , and the search for additional 
unreordered elements continued. If the user were to recompile the 
program, the following code should achieve the desired effect. 

if order (i) "= -1 then do; 
temp = strings ( i) ; 
do k = i repeat 1 while (order (k) "= i) ; 

1 = order (k) ; 

strings (k) = strings ( 1) ; 

order (k) = -I; 
end; 

strings (k) = temp; 
order (k) = -1; 
end; 

This approach may be checked before recompilation by making a 
slightly more elaborate patch than the one made previously. The probe 
command may be used to place a check for the correct terminating 
condition as the first thing in the loop on k and, if the condition is 
met, cause strings(k) to be set and the loop exited. First the break 
(containing the two value requests) previously set after the statement 
(line 78) is reset. Then a break, containing several requests and 
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extending across line boundaries, is sei 
the statement on line 39 of the program. 



(lines 80 through 84) before 



88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 

100 

101 

102 

103 

104 

105 

106 

107 

108 



Stopped before line 32 of sort_strings. 

reset 

Break reset before line 32 of so rt_strings . 

continue 

abc 

def 

hello 

nice 

probe 

xray 

r 743 0.357 1.582 42 



probe sort_strings 

status 

Break before line 39 

Break before line 21 

status at 21 

Break before line 21 



let 1 = -1 



r 744 0.184 1.146 72 



The program is run once again (line 33}, and the break set 
between the two sections is encountered again. As it is no longer of 
any use, the reset request (line 90), assuming the default of the last 
break encountered, is used to delete the break. The continue request 
(line 92) resumes the execution of the program. This time it works! 



The probe command is invoked once again. This time the status 
request is used to recall the breaks set, and, hence, the changes to 
be made to the program. Two forms of the status request are used. 
Just "status" (line 102) gives a list of all breaks set in the 
program; "status at line_number" (line 105) gives the text of the 
associated break request list. The user can now edit and recompile 
the program and expect i t to work correctly. The remaining breaks 
need not be reset, because a recompilation has the same effect. 
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active - a procedure is said to be active if its execution is 
ongoing or suspended by an error, quit signal, breakpoint, 
or call. An active procedure should be distinguished from 
one that has never been run, has completed execution, or has 
been interrupted and aborted by a Multics release command. 

automatic storage - a storage class for which space is allocated 
dynamically in a stack frame upon block invocation. As a 
result, variables of this class only have storage assigned 
to them, and hence a legitimate address and value, when the 
block in which they are declared has an active invocation. 
PL/I variables, by default, belong to this class. FORTRAN 
variables must appear in an "automatic" statement in order 
to belong to this class, 

block - corresponds to a PL/l' procedure or begin block or FORTRAN 
program or subroutine, and identifies a particular group of 
variable declarations. 

breakpoint - a point at which program execution is temporarily 
interrupted and probe requests executed. 

invocation - when a procedure -is called recursively, it will 
appear on the stack two or more times, and will have storage 
allocated for it the same number of times. Each instance of 
the procedure on the stack is considered a separate and 
distinguishable invocation of the block. The values of 
automatic variables can be different in different 
invocations of the same block. The most recent invocation 
is the topmost in stack trace, 

level number - an integer used by probe to uniquely designate 
each block invocation (i.e., each entry in a stack trace). 
Level one is the first (least recent) procedure invoked. 
Level number is not necessarily the same as either of the 
numbers given after the word "level" in a ready message. 
The first of this pair gives the count of command levels in 
effect and gives the value n+1, where n is the number of 
programs (or groups of programs) whose execution has been 
suspended, the second gives the number of stack frames in 
existence and since the probe stack includes quick blocks, 
this number is less than or equal to the level number of the 
last command level in the stack trace. 
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quick block - internal procedures and begin blocks that satisfy 
certain requirements (e.g., are not called recursively, do 
not contain on, signal, or revert statements, etc.) have 
their automatic storage allocated by the blocks that call 
them. Hence, they do not actually have their own stack 
frames, but share the one of the caller. Certain system 
commands, such as trace_stack, ignore these blocks. The 
probe command, however, includes them in a stack trace, and 
treats them as if they were the same as any other blocks. 
The quickness of a block may be determined from a program 
listing containing information about the storage requirement 
of the program (produced with the -symbols, -map, or -list 
control arguments) . For example, procedure "quick" shares 
stack frame of external procedure "main". 

stack - if a procedure A calls another procedure B, then the 
execution of A is suspended until 3 returns. If B in turn 
calls C, then this is an ordered list of procedure or 
subroutine calls indicating which program called which other 
program, and which will return to which. This ordered list 
is called the "stack". In probe, a trace of the stack may 
be displayed by use of the stack request. The list is given 
in top-down fashion with the most recently called procedure 
listed first: 

i /■? 
j *~ 

2 B 

1 A 

The numbers are level numbers. 

stack frame - when a block is invoked (that is, a procedure is 
called or a begin block is entered), storage is allocated 
for its automatic variables. The area allocated is called a 
stack frame and logically corresponds to each entry in the 
stack . 

static storage - a storage class for which space is allocated 
once per process, effectively at the time the procedure is 
first referenced. As a result, variables of this class 
always have a legitimate address and value. Regular FORTRAN 
variables, and those in a common block, have static storage. 
PL/I variables must be explicitly declared. 

support procedure - a system utility routine that provides 

runtime support for other procedures (e.g., the procedure 

that allocates storage as requested by a PL/I allocate 
statement) . 
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Summary of Re quests 
after a 

before b 

call cl 



.-• •> I-l +■ 1 Tt ) 1 ^ 



execute 


goto 


halt 


if 


let 


mode 


pause 


position 


quit 


reset 


source 


stack 


status 


step 


symbol 


use 


value 


where 


while 



e 

g 

h 
(none) 

1 
(none) 

pa 
ps 

q 

r 

sc 

sk 

st 

s 

sb 

u 

V 

wh 
wl 



Set a break after a statement. 

Set a break before a statement. 

Call an external procedure. 

Return from n robe» 

Execute a Multics command. 

Transfer to a statement. 

Stop the program. 

Execute commands if condition is true. 

Assign a value to a variable. 

Turn brief message mode on or off. 

Stop a program once. 

Examine a specified statement or locate 
a string in the program. 

Return to command level. 

Delete one or more breaks. 

Display source statements. 

Trace the stack. 

Display information about breaks. 

Advance one statement and halt. 

Display the attributes of a variable. 

Examine the block specified. 

Display the value of a variable. 

Display the value of probe pointers. 

Execute commands while condition is 
true. 
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de on or off, 

pause pa -Stop a program once. 

position ps Examine a specified statement or locate a string in the 
prog ram . 

quit q Return to command level. 

reset r Delete one or more breaks. 

source sc Display source statements. 

stack sk Trace the stack. 

status st Display information about breaks. 

step s Advance one statement and halt. 

symbol sb Display the attributes of a variable. 

use u Examine the block specified. 

value v Display the value of a variable. 

where wh Display the value of probe pointers. 

while wl Execute commands while condition is true. 
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Name : profile 

The profile command is a debugging tool used in conjunction with 
the -profile (-pf) control argument of the pll, fortran, and cobol 
commands. The profile command prints information about the execution 
of each statement in the PL/I, COBOL, or FORTRAN program. 

mUa, -nr^fil a .-• r\ ?-» *- ▼• s\ 1 arrrnmont- n A n <= *a q f h A rnfflDllflr tQ OPnefatS 3n 

internal static table containing an entry for each statement in the 
source program; the table entry contains information about the 
statement as well as a counter that starts out at zero. The counter 
associated with a statement is increased by one each time the 
statement is executed. The profile command prints and resets these 
counters. 



Usage 

profile paths {-control_args} 

wh ere: 

1. paths 

are the pathnames or reference names of programs whose 
counters are to be printed or reset. 

2. control_args 

are selected from the following list. Control arguments 
apply to all programs whose names appear in the command 
line. 

-print, -pr 

prints the following information for each statement in the 
specified programs: 

1. line number 

2. statement number, if greater than 1 

3. number of times the statement has been executed 

4. cost of executing the statement measured in number of 
instructions executed online plus the number of PL/I 
operators invoked. Each instruction and each 
operator invocation count as only one unit. 

5. the names of all the PL/I operators used by this 
statement 

6. total cost for all statements is printed at the end 
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-brief, -bf 

omits from the statement list statements that have never 
been executed. 

-long, -Ig 

includes in the statement list statements that have never 
been executed. 

-reset, -rs 

causes profile to reset to zero all counters associated 
with the specified program. 

Note 

If no control arguments are given, the default control arguments 
are -print and -brief. 



Example 

The PL/I program shown below counts the number of occurrences of 
one string in another string. It was compiled with the -profile 
control argument and executed once. Notice that line number and 
statement number (LINE and ST, respectively) of the statement in the 
then clause is the same as the line number and statement number of the 

1 f «}- a i- am on t- i hsal f 



The source code for the program is: 



1 example: proc(sl,s2); 
2 

3 declare (sl,s2) char(*) , 

4 (i,k) fixed bin, 

5 i° a _ options (variable); 
6 

7 k = 0; 

8 do i = I to length (si) - length (s2); 

9 if substr (si, i ,iength(s2) } = s2 

10 then k = k + 1; 

11 end; 
12 

13 call ioa_(""d",k) ; 

14 end example; 
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After executing the program once and invoking the profile command 
without any control arguments, the output is: 

LINE ST 



7 

8 

3 

9 

9 

11 

13 

14 



TOTAL 114+2 



UNT 


COST 


PROGRAM 
example 


1 


1 




1 


5 




8 


24 




7 


56 




1 


1 




7 


14 




1 
1 


13+1 
0+1 


(call_ext_out_desc) 
( return) 
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Name : reset_external_variables 

The reset_external_variables command reinitializes system-managed 
variables to the values they had when they were allocated. 

Usage 

reset_external__variables names {-control arg} 

wh e r e : 

1 . names 

are the names of the external variables, separated by 
spaces, to be reinitialized. 

2. control_arg 

is -unlabeled_common (or -uc) to indicate unlabeled (or 
block) common. 



Note 

A variable cannot be reset if the segment containing 
the initialization information is terminated after the 
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Name : resolve_linkage_error , rle 

The resolve_linkage__error command is invoked to satisfy the 
linkage fault after a process encounters a linkage error. The program 
locates the virtual entry specified as an argument and patches the 
linkage information of the process so that when the start command is 
issued the process continues as if the original linkage fault had 
located the specified virtual entry. 

Usage 

resolve_linkage_error virtual_entry 

where virtual_entry is a virtual entry specifier. 

Notes 

For an explanation of virtual entries, see the description of the 
cv_entry_ subroutine. 



Examples 



! myprog 

Error: Linkage error by >udd>m>vv>myprog i 123 

referencing subroutine$entry 

Segment not found. 

r 1234 2.834 123.673 980 level 2, 26 

1 rle mysub$mysub_entry 

r 1234 0.802 23.441 75 level 2, 26 

I start 

... myprog is running 
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Name : run_cobol, re 

The run_cobol command explicitly initiates execution of a COBOL 
run unit in a specified "main program". This command is not needed to 
execute COBOL object programs on Multics; it is used to simulate an 
environment in which traditional COBOL concepts may be easily defined. 
This command cannot be called recursively. 



Usage 

run_cobol name { -control_args} 

1 . name 

is the reference name or pathname of the "main program" in 
which execution is to be initiated. If _ a pathname is 
given, then the specified segment is initiated with a 
reference name identical to the entryname portion of the 
pathname. Otherwise, the search rules are used to locate 
the segment. If the name specified in the PROG-ID 
statement of the COBOL program (i.e., the entry point 
name) is different from the current reference name of the 
object segment, then the name specified here must be in 
the form A$3 where A is the pathname or reference name of 
the segment and B is the PROG-ID as defined in the 
IDENTIFICATION DIVISION of the source 

2. control_args 

can be chosen from the following: 

-cobol_swi tch N, -cs N 

sets one or more of the eight COBOL-defined "external 
switches" on, where N is a number from 1 to 8 (or a series 
of numbers separated by spaces) that corresponds to the 
numbered external switch. At the outset of the run unit, 
the default setting of these external switches is off. 
(The eight external switches are defined in the Multics 
COBOL Reference Manual , Order NO.IAS44.) 

-no_stop_run , -nsr 

avoids establishment of a handler for the stop_run 
condition. (See "Notes" below.) 

-sort_dir path, -sd path 

specifies the directory to be used during execution of 
this run unit for temporary sort work files. If this 
control argument is not specified, the process directory 
is assumed. 

-sort_f ile_size N, -sfs N 

is the floating point representation of the estimated 
average size in characters of the files to be sorted 
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during execution of this run unit. This information is 
used to optimize sorting. If not specified le6 is assumed 
(i.e., one million characters). 

Notes 

This command enables the user to explicitly define and start 
execution of a COBOL run unit. A run unit is either explicitly 
started by the execution of the run_cobol command or implicitly 
started by the execution of a COBOL object program either by 
invocation from command level or from a call by another program 
written in COBOL or another language. A run unit is stopped either by 
the execution of the STOP RUN statement in a COBOL object program or 
by invocation of the stop_cobol_run command. For the duration of time 
after a run unit is started and before it is stopped, it is said to be 
active. All COBOL programs executed while a run unit is active are 
considered part of that run unit. 

A run unit is a subset of a Multics process; it is stopped when 
the process is ended. Also, when all programs contained in a run unit 
are * cancelled, the run" unit is stopped (refer to the 
cancel cobol program command) . Only one run unit may be active at any 
given time in a process; thus, the run_cobol command cannot be invoked 
recursively. Additionally, if a run unit has been started implicitly 
(as described above) , the run_cobol command may not be used until that 
run unit has been stopped; i.e., the run_cobol command does not 
terminate a currently active run unit. 

The explicit creation of a run unit with the run_cobol command 
performs the following functions: 

1. Establishment of a "main program", i.e., a program from 
which control does not return to the caller. The EXIT 
PROGRAM statements, when encountered in such a program, have 
no effect, as required in the COBOL definition. An 
implicitly started run unit has no "main program". The EXIT 
PROGRAM statement in all programs contained in such a run 
unit always causes control to be returned to the caller, 
even if the caller is a system program, e.g., the command 
processo r . 

2. Setting of the COBOL external switches. These switches are 
set to • off unless otherwise specified by the -cobol_switch 
control argument. 

3. User control of the action taken when a STOP RUN statement 
is executed in a COBOL object program. The action normally 
taken for STOP RUN is cancellation of all programs in the 
run unit, closing any files left open. After this has been 
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done, the data associated with any of the programs is no 
longer available. Thus in a debugging environment, it may 
be useful to redefine the action taken for STOP RUN. When 
the run unit is explicitly initiated with the run_cobol 
command, the STOP RUN statement causes the signalling of the 
stop_run condition for which a handler is established that 
performs the normal action described above. If the 
-no_stop_run control argument is specified, the handler is 
not established, thus allowing the user to handle the signal 
himself using other Multics commands. If the user has not 
provided a handler himself for stop__run and specifies the 
-no_stop_run control argument, an unclaimed signal results. 

The name given in the run_cobol command need not be a C030L 

object program. It may be a program produced by any language compiler 

that provides a meaningful interface, with COBOL programs (e.g., PL/I, 
FORTRAN) . 

Refer to the following related commands: 



display_cobol_run_unit , dcr 
stop_cobol_run, scr 
cancel_cobol_program, ccp 
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Name ; set_fortran_common, sfc 

The set_fortran_common command allocates and initial izes _ all 
FORTRAN common blocks referenced by the specified FORTRAN object 
segments. The maximum declared length of a common block (of all those 
found in the list of FORTRAN object segments) is used for the 
allocation and initialization. This command can therefore be used to 
,^, ,.,,.,„*. «„ ^v.-3-i- i-Viq i-nyr'ai^i- r-nmm/-in hli-ir-V <;t-nraap is allocated and 

initialized prior to a FORTRAN run. (If the user left it to the 
dynamic linker, the first reference to the common block would cause it 
to be allocated and initialized as declared in the referencing 
program. This program might not include the necessary initialization 
information.) The set_fortran_common command can also be used to 
reinitialize the common blocks referenced by the specified object 
segments, although it will not reinitialize any local storage such as 
static or automatic variables. 



Usage 

set ■ fortran_common paths {-control_arg} 

where : 

1. paths 

are the pathnames of the FORTRAN object segments whose 
common blocks are to be allocated and ( re) initial ized . 

2. control_arg 

can be -long (-lg) indicating that warning messages are to 
be printed. Normally, all warning messages are 
suppressed. Warnings are printed if the common block is 
already allocated with a smaller size. 

Notes 

A FORTRAN object segment is either a segment created by one of 
the Multics FORTRAN compilers or is a segment created by the binder 
and contains at least one component that was created by one of the 
Multics FORTRAN compilers. 

Only common storage is affected by this command. Local variables 
are not ( re) initial ized . 

Common blocks without data initialization information are set to 
binary zeros. 
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If the common block is already allocated, its contents are 
reinitialized and the prior contents are lost. 

A warning is always printed if different initialization values 
are encountered in the set of specified object segments. 



Not To 3e Reoroduced A-35 F21 



set system storage 



Name ; set_system_storage 

The set_system_storage command establishes an area as the storage 
region in which normal system allocations are performed. 

Usage 

set_system_storage {virtual_ptr -control__arg} 

where : 

1. virtual__ptr 

is a virtual pointer to an initialized area. The syntax 
of virtual pointers is described in the cv_ptr_ subroutine 
description. This argument must be specified only if the 
-system control argument is not supplied. 

2. control_arg 

is -system to specify the area used for linkage sections. 
This control argument must be specified only if 
virtual_ptr is not specified. 

Notes 

To initialize or create an area, refer to the description of the 
create_area command. 

The area, must be set up as either zero_on_free or zero_on_alloc . 

It is recommended that the area specified be extensible. 

Examples 

The command line: 

set_system_storage free_$free_ 

places objects in the segment whose reference name is free_ at the 
offset whose entry point name is free_. 
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The command line: 

set_system_storage my_seg$ 

uses the segment whose reference name is my_seg . The area is assumed 
to be at an offset of in the segment. The segment must already 
exist with the reference name my_seg and must be initialized as an 
area. 

The command line: 

set_system_storage my_seg 

uses the segment whose (relative) pathname is my_seg . The segment 
must already exist. 
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Name ; set_user_storage 

The set_user_storage command establishes an area as the storage 
region in which normal user allocations are performed. These 
allocations include FORTRAN common blocks and PL/I external variables 
whose names do not contain dollar signs. 

Usage 

set_user_storage {virtual_ptr -control_arg} 



where 



virtual_ptr 

is a virtual pointer to an initialized area. The syntax 
of virtual pointers is described in the cv__ptr_ subroutine 
description. This argument must be specified only if the 
-system control argument is not specified. 

control_arg 

is -system to specify the area used for linkage sections. 
This control argument must be specified only if 
virtual ptr is not specified. 



Notes 

To initialize or create an area, refer to the description of the 
create_area command. 

The area must be set up as either zero_on__f ree or zero_on_alloc . 

It is recommended that the area specified be extensible. 

Examples 

The command line: 

set_user_storage free_$free_ 

places objects in the segment whose reference name is free_ at the 
offset whose entry point- name is free_. 
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The command line: 

set_user_storage my_seg$ 

uses the segment whose reference name is my_seg . The area is assumed 
to be at an offset of in the segment. The segment must already 
exist with the reference name my_seg and must be initialized as an 

area. 

The command line: 

set_user_storage my_seg 

uses the segment whose (relative) pathname is my_seg . The segment 
must already exist. 



Not To 3e Reproduced A-89 F21 



stop cobol run, scr 



Name : stop_cobol_run, scr 

The stop_cobol_run command causes the termination of the current 
COBOL run unit. Refer to the run_cobol command for information 
concerning the run unit and the COBOL runtime environment. 



~-> - 

stop_cobol_run { -control_arg} 

where the control_arg may be -retain_data or -retd to leave the data 
segments associated with the programs composing the run unit intact 
for debugging purposes. (See "Notes" below.) 

Notes 

The results of the stop_cobol_run command and the execution of 
the STOP RUN statement from within a COBOL program are identical. 
Stopping the run unit consists of cleaning up all files that have been 
opened during the execution of the current run unit, and ensuring that 
the next time a program that was a component of this run unit is 
invoked, its data is in its initial state. 

To maintain the value of all data referenced in the run unit in 
its last used state, the -retain_data control argument should be used. 

Refer to the related commands: 

display_cobol__run_unit , dcr 
cancel__cobol_program, ccp 

r un CQDQ-t/> re 
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Name : trace 

The trace command is a debugging tool that lets the user monitor 
all calls to a specified set of external procedures. The trace 
command modifies the standard Multics procedure call mechanism so that 
whenever control enters or leaves one of the procedures specified by 
the user, a debugging procedure is invoked. The user can request the 
following : 

1. Print the arguments at entry, exit, or both. 

2. Stop (by calling the command processor) at entry, exit, or 
both. 

3. Change the frequency with which tracing messages are printed 
(e.g., every 100 calls, after the 2000th call, only if the 
recursion depth is less than five, etc.) . 

4. Execute a Multics command line at entry, exit, or both. 

5. Meter the time spent in the various procedures being 
monitored. 

Use of the trace command is subject to the following 
restrictions: 

1. Only external procedures compiled by PL/I or FORTRAN can be 
traced. 

2. Ring or gate entries cannot be traced. 

3. Incorrect execution results if the traced procedure looks 
back a fixed number of stack frames, e.g., cu_$arg_ptr 
cannot be traced. 

4. Only 100 procedures can be traced at one time. Up to 16 
locations can be watched at one time. 

5. The procedure being traced and the trace package itself must 
share the same combined linkage segment. 

6. A procedure in a bound segment can only be traced if its 
entry point is externally available. 

Usage 

trace {-control_args} names 
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where: 

1. names 

is a pathname or reference name. The reference name or 
entry portion of a pathname is used in the trace table. 
(See "Notes" below.) 

2. control_args 

apply to the namejL arguments that follow, and, if 
applicable, change the current value in the trace control 
template (TCT) . (See "Notes" below.) Control arguments 
may be chosen from the following: 

-after N 

calls the command processor after calling the traced 
procedure every N times (initial value!=!0: do not call). 

-argument N, -ag N 

prints the arguments every Nth time the procedure is 
entered (initial value!=I0: do not print). 

-before N 

calls the command processor before calling the traced 
procedure every N times (initial value!- 10: do not call) . 

-brief, -bf 

prints a short form of the monitoring information. 

-depth N, -dh N 

monitors to the maximum recursion depth of N (initial 
value!=!0: no limit). 

-every N, -ev N 

monitors every Nth call (initial value!=!l). 

-execute STR, -ex STR 

executes the Multics command line specified by the string 
STR whenever the procedure is monitored (initial 
value!=!" n : no command). 

-first N, -ft N 

starts monitoring on the Nth call (initial value!=!l). 

-govern STR, -gv STR 

limits/does not limit the recursion level for a procedure, 
where STR can be the string on or off (initial 
value! = !of f ) . See "Recursion Limiting" below. 

-in 

prints the arguments only on entry (initial value!= lyes) . 
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-inout 

prints the arguments on both entry and exit (initial 
value!=!no) . 

-io_switch STR, -is STR 

changes the switch for output to the switch specified by 
STR. (See "Changing Output Switch" below.) 

-last N, -It N 

stops monitoring after the Nth call (initial 

valuei=i9999999999) . 

-long, -lg 

prints the long form of the monitoring information. (For 
use after the -brief control argument to restore the long 
form.) 

-meter STR, -cut STR 

meters/does not meter the time spent in the procedure, 
where STR can be the string 'on or off' (initial 
valuei=!off) . See "Metering" below. 

-out 

prints the arguments only on exit (initial valuei=!no). 

-off entryname 

StoDS mon i t-n r i na h'n« ensrifion nrAca^ m- a TK .= nr ^^<^A n v a 

remains in the trace table and calls continue to be 
counted. 

-on entryname 

resumes monitoring the specified procedure. This control 
argument is used after the -off control argument. 

-remove entryname, -rm entryname 

removes the specified procedure from the trace table. 
Tracing can be removed at any time. 

-reset entryname, -rs entryname 

sets the number of calls and recursion depth of the 
specified procedure to zero, 

-return_value STR, -rv STR 

prints/does not print the return value on exit, where STR 
can be the string on or off (initial value! = ! of f ) . This 
control argument assumes the entry is a function. 

-status * , -st * 

prints the procedures being monitored and their counters. 
(See "Notes" below.) 
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-status entryname, -st entryname 

prints the trace parameters and counters for the procedure 
specified by entryname. (See "Notes'* below.) 

-stop_proc path, -sp path 

changes the procedure that is called for stop requests 
from the command processor to the procedure specified by 
path. To reset the stop procedure, issue this control 
argument with no path argument. 

-subtotal, -stt 

prints and does not clear the metering statistics. 

-template, -tp 

lists the trace control template. 



Notes 



The procedure whose pathname is given in the command line is added 
to the trace table with the tracing parameters from the trace control 
template (TCT) . If the procedure is already in the table, the 
counters are reset and the current parameters in TCT are used. 

For control arguments that affect procedures being traced, the 
argument is an entryname or an asterisk (*). If an entryname is used, 
the control 'argument applies to that procedure. If an asterisk is 
used, the control argument is applied to all entries in the trace 
table. All control arguments that affect the TCT must have a number 
argument (indicated by N above). 

Examples 

The command line: 

trace -ag 1 -inout test 
prints the arguments for test on entry and exit. 

The command line: 

trace -ag 2 -in -depth 6 test 

prints the arguments for test every second time test is entered up to 
a recursion depth of six, i.e., 2, 4, 6. 

The command line: 
trace -govern on test 
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prints the arguments of test each time test is called with a new 
maximum recursion depth. The trace procedure calls the command 
processor every time the recursion depth is a multiple of 10. 

The command line: 
trace -st * -tp 

lists the procedures in the trace table and prints the values of the 
trace control template. 
Message Format 

The message printed when control enters a procedure can appear in 
any one of several formats, depending on the setting of the brief 
switch and the status of the calling procedure. If the calling 
procedure is unbound or occurs in a bound segment containing a 
bindmap, the message takes the form: 

Call 4.1 of alpha from beta!l27, ap = 204110746. 

This is the fourth call of procedure alpha, which is at recursion 
level 1. The call comes from location 127 in component beta, and the 
argument list is at 204 110746. If the procedure making the call is in 
a bound segment that does not contain a bindmap, the message takes the 
f o rm : 

Call 4.1 of alpha from bound_gamma| 4 37 (beta), ap = 204110746. 

The name in parentheses may not always be available and may be omitted 
in some cases. If the user has requested the brief output mode, the 
message is shortened to: 

Call 4.1 of alpha. 

When tracing is requested for a procedure, the parameters for that 
entry are taken from the trace control template (TCT) . If the user 
does not alter the values in the TCT, the initial default values are 
used (see below). The initial values in the TCT specify that every 
call should be monitored. 
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Trace Control Template 

As mentioned earlier, the trace table entry holds a number of 
parameters for each procedure to be traced. The values of the 
parameters are determined by the contents of the TCT at the time the 
table entry is filled in. These parameters are used in conjunction 
with N (the number of calls to the traced procedure in this process) 
and R (the current recursion depth) to control when and how the 
-rocedure should be monitored. The execution count (N) is set to o 
when = tracing W is~ first started and is incremented by 1 every time the 
traced procedure is called. The recursion depth (R) is set to when 
tracing is first started and is incremented by 1 every time control 
enters the traced procedure and is decremented by 1 every time control 
leaves the traced procedure. 



Let: 

D = 

F = 

L = 

c - 

B = 

A = 

AG = 



the maximum recursion depth to be monitored (-depth) 

the number of the first call to be monitored (-first) 

the number of the last call to be monitored (-last) 

how often monitoring should occur (-every) 

the number of times the procedure is^ called^ before trace 

stops at entry to the traced procedure (-before) 

the number of times the procedure is called before trace 

stops at exit from the traced procedure (-after) 

the number of times the procedure is called before trace 



prints the arguments of the traced procedure ^(-argument) 



= a 



bit that is "l"b if the tracing procedure should print the 



nto the 



arguments of the traced procedure when control goes 
traced procedure (-in) . 

= a bit that is "l"b if the tracing procedure should prmt^the 
arguments of the traced procedure 
the traced procedure (-out) 



when control goes out 



only i 



A call 



is monitored and 



the tracing procedure is called if, and 



F <= N <= L 

R <= D 
mod(N,E) = 



If AG 



"= 0, mod(N,abs(AG) ) = 0, and 



values of the arguments (if any) being passed to 
All of the arguments are listed when AG < . If 
is assumed to be a function and the value of 
printed' after the procedure returns. 



'l"b, trace prints the 
the traced procedure. 
AG < , the procedure 
the last argument is 
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If B "= and mod(N,B) = 0, the monitoring procedure prints 
"Stop" and calls the command processor (or a user-set procedure if the 
-stop_proc control argument was used) . This call occurs before the 
procedure being traced has created its stack frame. 

After control leaves the traced procedure, trace prints a line of 
the form: 



Return N.R from alpha. 

■If AG ~ = and mod(N ,abs( AG) ) = 0, then all of the arguments of 
the traced procedure are printed if = "l"b; otherwise, if AG < 0, 
the value of the last argument (assumed to be the value of the 
function) is printed. 

Finally, trace calls the command processor. If the -stop_proc 
control argument was given, a procedure set by the user is called. 
This call occurs after the stack frame of the procedure being traced 
has been destroyed. 

Metering 

The trace command can be used to meter the execution of a 
specified set of procedures. If the metering feature is being used, 
trace does not call the debugging procedure when control enters a 
procedure being traced; instead, it determines the current time and 
the virtual CPU time used, and the number of page faults taken by the 
user's process before control enters and after control leaves the 
traced procedure. This information is used to compute the real time 
and CPU time used, and the number of page faults taken by the traced 
procedure on a local and global basis. The global CPU time is the 
time spent in the procedure including the time spent in any procedures 
that it calls. The local CPU time does not include the time spent in 
any traced procedure called by the procedure, but it does include time 
spent in called procedures that are not being traced. The local and 
global versions of real time and page faults are calculated in a 
similar manner. Metering is only done when the first, last, every, 
and depth tracing conditions are satisfied. 

The control argument: 

-meter on, -mt on 
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sets the metering switch in the TCT; any procedures added to the trace 
table or that have their table entries updated after this argument is 
used are metered. 

The control argument: 

-meter off, -mt off 

turns off the metering switch in the TCT; any procedures currently 
being metered continue to be metered. 

The control argument: 

-total 

causes trace to print the metering statistics of all procedures in tie 
trace table. The output gives the number of calls (#CALLS), global 
CPU time (GCPU) , global real time (GREAL) , global page waits (GPWS' , 
local CPU time (LCPU) , local real time (LRSAL) , local page wai:s 
(LPWS) , and the usage percentage (%USAGS) based on local CPU time, ;f 
all the procedures being metered. The metering statistics are set co 
after they are printed. 

The control argument: 

-subtotal, -stt 

prints the same information as the -total control argument, but dc ?s 
not clear the statistics. 
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Recursion Limiting 

The control argument: 

-govern on, -gv on 

sets a bit in the TCT that causes recursion limiting to be in effect 
for any procedure subsequently added to the trace table. When the 
governing ^feature is used, the depth control parameter is ignored and 
trace prints the call message only when the" recursion depth of the 
traced procedure reaches a new, maximum depth. Each call message has 
a ^recursion depth one greater than the previous call message. in 
addition, trace calls the command processor (or a user-defined 
procedure if the -stop_proc control argument was used) whenever the 
recursion depth is a multiple of 10. Return messages are not printed. 
This feature enables the user to find and limit uncontrolled 
recursion; it can be very useful in finding the procedure(s) 
responsible for fatal process error. 

The control argument: 

-govern off, -gv off 

turns off the governing switch in the TCT; any procedure currently 
being governed continues to be governed. 

Watch Facility 

The trace command has an optional watch facility in which trace 
watches the contents of a set of previously specified memory cells. 
The cells are checked at every entry to and every exit from every 
traced procedure. As long as the values in the locations being 
watched remain the same, no action is taken and no tracing messages 
are printed. The tracing message is printed as soon as trace finds 
that any of the locations being watched has had its value changed. 
This can be found either at entry to or exit from the traced 
procedure. When any value changes, the tracing message is preceded by 
lines that give the new values of all of the locations that have 
changed, and the command processor (or a user-set procedure if the 
-stop_proc control argument was used) is called even" if the A or B 
conditions are not met. When execution continues, the locations that 
have changed are watched with the new value being used in subsequent 
checks. This feature can be very useful in determining which of the 
user's procedures has incorrectly modified a word of storage. 
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The control argument: 

-watch STR, -wt STR 

causes all procedures being traced to watch for a change in the 
current contents of the memory word(s) specified by the string STR. 
This et-rinn. <?n<»c i f vi no t-h(> location, can consist of a sinale address 
specification or a series of address specifications separated by 
blanks and surrounded by quotes. If an address specification does not 
contain a vertical bar (I), it is taken to be an octal number giving a 
location in the stack; otherwise, it is taken to be a segment number 
and offset in octal in the standard form, e.g., segment_number I off set . 

The control argument: 

-watch off, -wt off 
turns off the watch facility. 

The watch facility differs from other trace facilities in that 
there is a single table of locations being watched that is used by all 
procedures being traced. When the -watch control argument_ is 
processed, the new location(s) specified replace any locations 
currently in the watch table. There is no provision made for removing 
a single location from the watch table; the user must reissue a watch 
request that omits the location to be removed from the table. 

Command Execution 

The command execution facility of trace allows the user to 
specify a Multics command line to be executed whenever the trace 
debugging procedure is called. The trace procedure calls the command 
processor with the specified string after printing the tracing 
message, but before the stop request causes the command processor to 
be called. 
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The control argument: 

-execute string 

sets the execution string parameter in the TCT. Since string is a 
single argument, it must be enclosed in quotes if it contains any 
spaces. The execution parameter in the TCT is turned off if string 
has zero length {-execute "") . The following line: 

trace -ex time test 



causes trace to execute the time command before and after test is 
called . 



Changing Output Switch 

All of the messages from the trace command that may b.e generated 
while actually monitoring procedures are normally written on the 
user_i/o switch so that trace can conveniently be used with procedures 
that change the attachment of the normal switch, user output. The 
control argument: 

-io_switch 3TR 

causes trace to write furthe-r monitoring output on the switch 
specified by STR, which must already be attached and opened for 
stream output. 
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Name: trace_stack, ts 

The trace_stack command prints a detailed explanation of the 
current process stack history in reverse order (most recent frame 
first) . For each stack frame, all available information about the 
procedure that established the frame (including, if possible, the 
source statement last executed), the arguments to that (the owning) 
procedure, and the condition handlers established in the frame are 
printed. For a description of stack frames, see "Multics Stack 
Segments" in Section! IV of the MPM Subsystem Writers' Guide. 

The trace_stack command is most useful after a fault or other 
error condition. If the command is invoked after such an error, the 
machine registers at the time of the fault are also printed, as well 
as an explanation of the fault. The source line in which it occurred 
can be given if the object segment is compiled with the -table option. 

Usage 

trace_stack {-control_args} 

where control_args can be selected from the following: 

-brief, -bf 

suppresses listing of arguments and handlers. This 
control argument cannot be specified if -long is also 
specified as a control argument. 

-long, -Ig 

prints octal dump of each stack frame. 

-depth N, -dh N 

dumps only N frames. 

Output Format 

When trace_stack is invoked, it first searches 
backward through the stack for a stack frame containing 
saved machine conditions as the result of a signalled 
condition. If such a frame is found, tracing proceeds 
backward from that point; otherwise, a comment is printed 
and tracing begins with the stack frame preceding 
trace_stack. 

If a machine-conditions frame is found, trace_stack 
repeats the system error message describing the fault. 
Unless the -brief control argument is specified, 
trace_stack also prints the source line and faulting 
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instruction and a listing of the machine registers at the 
time the error occurred. 



The command then performs a backward trace of the 
stack, for N frames if the -depth N argument was 
specified, or else until the beginning of the stack is 
reached . 



For each stack frame, trace_stack prints the offset 
of the frame, the condition name if an error occurred in 
the frame, and the identification of the procedure that 
established the frame. If the procedure is a component of 
a bound segment, the bound segment name and the offset of 
the procedure within the bound segment are also orinted. 



The trace_stack command then attempts to locate and 
print the source line associated with the last instruction 
executed in the procedure that owns the frame (that is, 
either a call forward or a line that encountered an 
error). The source line can be printed' only if the 
procedure has a symbol table (that is, if it was compiled 
with the -table option) and if the source for the 
procedure is available in the user's working directory. 

comment explaining why. ~ 



Next, trace_stack prints the machine instruction last 
executed by the procedure that owns the current frame. If 
the machine instruction is a call to a PL/I operator, 
trace_stack also prints the name of the operator. If the 
instruction is a procedure call, trace_stack suppresses 
the octal printout of the machine instruction and prints 
the name of the procedure being called. 



Unless the -brief control argument is specified, 
trace_stack lists the arguments supplied to the procedure 
that owns the current frame and also lists any enabled 
condition, default, and clean-up handlers established in 
the frame. 



If the -long control argument is specified, 
trace_stack then prints an octal dump of the stack frame, 
with eight words per line. 
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Example 

After a fault that reenters the user environment ?nd 
reaches command level, the user invokes the trace_stack 
command. 

For example, after quitting out of the list command, 
the following process history might appear: 

i list 

Segments=8 , Records=3 

rew mailbox 

r w 

QUIT 

trace stack 

quit Tn ipc_$block 1 156 

(>system_library_l>bound_command_loop_! 156) 

No symbol table for ipc_ 
156 400010116100 cmpq pr4ll0 

Machine registers at time of fault 

pro fao) 263 14656 pll_operators_$operator_table| 162 

(external symbol in separate nonstand 

text section) 
prl (ab) 1031264 scs!264 

or2 (bp) 14112200 as_l inkagel 12200 

pr3 (bb) 11310 tc_data!0 

pr4 (lp) 25312250 I 3BBJG jFkPBWcNZ .area .1 inker 1 2250 

(internal staticlO for ipc_) 
pr5 (lb) 24413614 Stack_4l3614 

P r6 (sp) 244 13500 stack_4 13500 ( -> "kcpMbLH +0000000") 

pr7 (sb) 244 i0 stack_4 1 

x0 73 xl x2 x3 600000 
x4 x5 32 x6 3033 x7 4 
a 000000000000 q 000000000004 e 
Timer reg - 1746005, Ring alarm reg - 

SCU Data: 

4030 400270250011 000000000021 400270000000 000000672000 
000156000200 000154000700 002250370000 600044370120 

Connect Fault (21) 

At: 270 1156 ipc_|156 (bound_command_loop_l 156 ) 

On: cpu a (#0) 

Indicators: "bar 
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APU Status: xsf, sd-on, pt-on, fabs 
CU Status: rfi, its, fif 
Instructions: 

4036 002250 3700' 00 epp4 

4037 6 00044 3701 20 epp4 



2250 

pr6 144,* 



Time stored: 03/02/77 1535.5 edt Tue (104541674361226602) 
Ring: 4 

Backward trace of stack from 24413500 



3500 quit ipc_$block| 156 (bound_command_loop_! 156) 
No symbol table for ipc_ 
156 400010116100 cmpq pr4il0 

ARG 1: 25315704 ! BBBJGj FkPBWcNZ .area .1 inker | 5704 
ARG 2: 24413152 stack_4 13152 
ARG 3: 



ARG 



2720 tty_$tty_get_line 12442 ( bound_iox_l 11546) 
No symbol table for tty_ 
call_ext_out to ipc_Sblock 

25314320 ! BBBJGj FkPBWcNZ. area. linker! 4320 

(internal static! 154 for find_iocb) 
24412660 stack_4 12660 ( -> " f o stuff") 
123 





ARG 


2 


ARG 


3 


ARG 


4 


ARG 


5 



2400 listen_$listen_l461 (bound_command_loop_l 1325) 
No symbol table for listen_ 
call_ext_out to iox_$get_line 
ARG 1: "" 
on "cleanup" call listen_|255 (bound_command_loop_! 1122) 



\c 121433) 



2100 



process_overseer_$process_overseer_l 473 (bound_command_loop 



No symbol table for process_overseer 
call_ext_out_desc to listen_$listen_ 
Argument list header invalid, 
on "any_other" 

call standard_def aul t_handler_$standard_def aul t_handler_3 
(external symbol in separate nonstandard text section) 



\cl676; 



2000 



user_init_admin_$user_init_admin_| 3 6 (bound_command_loop_| 2 



No symbol table for user_init_admin_ 
21676 700036670120 tsp4 pr7)36,* alm_call 
No arguments. 



End of trace. 
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r 1635 1.756 40.790 207 level 2, 9 
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Workshops 
W-i 



WORKSHOP ONE 



A probe Workshop 

The best (perhaps the only) way of learning how to use the probe 
command is by using the command in actual debugging sessions. This 
workshop provides the experience of debugging a moderately complicated 
program. * The program computes and prints out the elements of a 
Fibonacci series. An F series begins as 

1 1 2 3 5 8 13 21 34 55 ... 

An element of the series is calculated by adding the previous 2 
elements (for a Fibonacci series of degree 2). In the series shown 
above, the first two elements (0 and 1) are given as initial values 
and the remaining elements are then computed. 

Fibonacci series of higher degrees can also be defined by adding more 
elements to calculate the next in the series. For example, a series 
of degree 4 begins as 

1 1 2 4 8 15 29 56 103 .. . 

with the next element of the series calculated by adding the previous 
4 elements in the series. 

The program shown below reads two parameters from the terminal: Fdeg 
gives the number of the highest degree Fibonacci series _ to be 
computed; count gives the number of elements to be included in each 
series. For input of 

Fdeg=4, count=7; 

the first seven elements (excluding the assumed initial values) of the 
Fibonacci series of degrees 2, 3, and 4 are printed. 

Now, without further ado, here are the orograms! There is one written 
in PL/I, and one written in FORTRAN. ?ou can copy whichever of these 
programs you wish to debug from >udd>F19>Student_0i>f ib.pli (or 
.fortran) into your home directory. Note that the line numbers shown 
below are not actually a part of the so-.rce segment. p \ «u 



7 .U7^ 7 ^ 7 ^ 
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1 fib: proc; 
2 

3 del (sysin, sysprint) file, 

4 Sfirst bit(l) int static init("l"b), 

5 (Fdeg, count, i) fixed bin, 

6 msg char (256) varying; 
7 

8 del linesize fixed bin, 

9 get_line_length_$ stream entry (char(*), fixed bin(35)) 
10 returns(f ixed bin); 

11 

12 del cleanup condition; 

13 

14 /* Establish cleanup on unit to close files. */ 

15 /* Open input/output files, get output file line */■ 

16 /* length to insure output lines fit on terminal. */ 
17 

18 on cleanup close file(sysin), file (sysprint) ; 

19 open file(sysin) stream input; 

20 open f ile(sysprint) stream output; 

21 linesize = get_line_length_$stream ("sysprint", 0); 
22 

23 /* Initialize indicator of how many series should */ 

24 /* be output (Fdeg) and how many items should be */ 

25 /* output in each series (excluding assumed */ 

26 /* initial elements of each series) . */ 
27 

28 ' Fdeg = 2; 

29 count = 10; 
30 

31 

32 /* Output brief instructions to the user, but */ 

33 /* only the first time fib invoked in each process*/ 
34 

35 if Sfirst then do; 

36 msg = 

37 "Enter Fdeg and/or count, followed by a ■■■;"■ character."; 

38 write f ile(sysprint) from(msg); 

39 msg = 

40 ' "For example, 

41 Fdeg = 2, count=10;"; 

42 write file( sysprint) from(msg); 

43 msg = 

44 "These are the default values. To stop, enter 

45 Fdeg = 1; 
46 

47 write f ile(sysprint) from(msg); 

48 Sfirst = "0"b; 

49 end; 

50 put f ile(sysprint) 

51 list ("Enter data, or just a "";"" char: "-) ; 

52 get file(sysin) data (Fdeg, count); 
53 
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54 /* Compute and output each Fibonacci series. */ 

55 /* Then get next set of input values. */ 
S'6 

57 do while (Fdeg < 1); 

5.8 /' put f ile(syspr int) skip(2) data (count); 

5$ put f ile(syspr int) skip; 

'60? . do i = 2 to Fdeg; 

6-1. . call gen_fib (i, count); 

62 end; 

63 put f ile(sysprint) 

6| list ("New data, or just a "";"" char: "); 

65 get file(sysin) data (Fdeg, count); 

66 end ; 

67 ■- 
68 

69 /* Close files and return. */ 

70; 

71 '* close file(sysin) , f ile(sysprint) ;. 

"'7.2*' return; 
73 
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74 gen fib: proc (grouping, count); 
75 

76 del (grouping, count) fixed bin, 

77 /* Fibonacci series to be computed, and number */ 

78 /* of items to be computed in the series. */ 

79 N (grouping) fixed bin(71), 

80 /* Array of values summed to form series elements*/ 

81 result (-grouping :count-l) char(28) varying, 

82 /* Array of output values, including assumed */ 

83 /* values which begin the series. */ 

84 r_matrix (Nrows, Ncols) char(28) varying based (Pr_matrix) , 

85 /* 2-dimensionai overlay for the computed output */ 

86 /* values (excluding assumed values) . */ 

87 Pr matrix ptr; 
88 

89 del (Icol, Irow, Ncols, Nrows, 

90 Nused cols in_last_row) fixed bin, 

91 Sdoes_not_I it bit(i), 

92 SPACES char(30) int static options(constant) init(" i! ) , 

93 cycle fixed bin, 

94 /* index of series element being computed. */ 

95 formatted_total pic "zzz,zzz,zzz ,zzz ,zzz ,zzz ,zz9" , 

96 output_total char (100) varying, 

97 total fixed bin(71); 
98 

99 

100 , /* Initialize the assumed values which begin */ 

101 /* the series. All are but the last, which is 1*/ 
102 

103 N(*) = 0; 

104 N (grouping-1) = 1; 
105 

106 

107 /* Put the assumed values in the output array. */ 

108 

109 do cycle = -grouping to -2; 

110 result(cycle) = "0"; 

111 end; 

112 result(cycle) = "1"; 
113 

114 

115 /* Compute remaining values of series, and put in */ 

116 /* the output array. */ 
117 

118 do cycle - to count-1; 

119 total = sum(N) ; 

120 formatted_total = total; 

121 result(cycle) = Itr im (formatted_total) ; 

122 N (mod (cycle, grouping)) = total; 

123 end; 
124 
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125 /* The output will be printed with assumed values */ 

126 /* preceding computed values. The computed values*/ 

127 /* will be printed in as many rows as possible to */ 

128 /* reduce the number of output lines. However, if*/ 

129 /* the output fits in 2 or more rows, the number */ 

130 /* of rows is chosen so that all columns but the */ 

131 /* final one are full (have Nrows values) . */ 

132 /* Of course, in multi-column format, all data */ 

133 /* must fit the terminal linesize. */ 
134 

135 Pr matrix = addr (result(O) ) ; 

136 Sdoes_not_fit = "l"b; 

137 do Ncols = 20 to 1 by -1 while (Sdoes_not__f it) ; 

1-SO *.,, 4- -, 1 — _1 . 

A JO uwuaj- — — £. , 

139 Nrows = divide(count+Ncols-l, Ncols, 17, 0); 

140 Nused_cols_in__last_row = mod (count , Ncols) ; 

141 if Nused_cols in last__row = then 

142 Nused_coTs_Tn_last_row = Ncols; 

143 if Nused_cols__in_last_row >= Ncols then do; 

144 do Icol = 1 to Nused__cols_in_last_row; 

145 total = total + 

146 length(r_matr ix (Icol , Nrows) )+2; 

147 end; 

148 do Icol = Icol to Ncols; 

149 total = total + 

150 length(r matrix(Icol, Nrows-l))+2; 

151 end; 

152 if total <= linesize then Sdoes_not_f it = "0"b; 

153 end; . 

154 end; 

155 Ncols = Ncols + 1; 
156 
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157 /* Output the values, starting with the assumed */ 

158 /* values, then the computed (output in columns) . */ 

159 /* Computed values are output in right- justified */ 

160 /* columns. Each row (line) is formatted and */ 

161 /* then output. */ 
162 

163 put file(sysprint) edit ("Fdeg =", grouping, 

164 -:■) (a, f(3), a); " 

165 put file(sysprint) edit ("(assumed beginning of series)", 

166 (result(cycle) do cycle=-grouping to -1)) 

167 (skip, a, skip, (grouping) (a , x(i))); 

168 put f ile(sysprint) 

169 edit ("(remainder of series) ") (skip, a); 

170 put f ile(sysprint) skip; 

171 do Irow = I to Nrows; 

172 msg =. ""; 

173 do Icol = 1 to Ncols-1; 

1 74 msg = msg M sufastr (SPACES, 1, 

175 length ( r_matr ix (Icol , Nrows)) - 
l" 76 length ( r~matr ix (Icol ,Irow) ) ) ; 

177 msg = msg j| r~matr ix (Icol , Irow) ; 

178 msg = msg 1 I " " ; 

179 end; 

ISO if lrow*Ncols + Icol <= count then do; 

181 msg = msg || substr (SPACES , 1, 

182 length(result(hbound(result,l) ) ) - 

183 length ( r_matr ix (Icol , Irow))); 

184 msg = msg || r matrix(Icol, Irow) • 

185 end; 

186 write f ile(sysprint) from (msg) ;" ! 

187 end; 

188 put skip(2) file(sysprint) ; 

189 end gen fib; 

190 ~ 

191 end fib; 
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A FORTRAN VERSION 



1 logical sfirst /.true./ 

2 save sfirst 
3 

4 c Output instructions to the user, but only the first 

5 c time 'fib' is invoked in each process. 
6 

7 if ( .not. sfirst) goto 10 

8 print, "Enter first degree and count" 

a nyinl- " Wn v avamnla Fir-Ct- HeOTPP = . Cflimt = 10" 

10 print, "To stop, enter First degree = 1" 

11 sfirst = .false. 

12 

13 c Prompt for First degree and count. 

14 10 print, "First degree, count?" 

15 read, ifdeg, icount 
16 

17 c Stop when First degree is 1. 

18 if (ifdeg - 1) 15,15,25 
19 

20 15 print, "Count =", icount 
21 

22 c Compute and output each Fibonacci series. 

23 c Then get next set of input values. 
24 

25 do 22 i = 2, ifdeg 

26 22 call gen_fib (i, icount) 

27 goto 10 
28 

29 25 stop 

30 end 
31 

32 

33 

34 subroutine gen_fib (igrouping, icount) 

35 

36 c This subroutine actually computes the Fibonacci series. 

37 c 'iresult' will be filled with the proper values, 

38 c while ' jresult' is a convenient equivalent view of 

39 c the solution which will be used for printing purposes. 

40 c The ' n' array holds the most recent terms to be added 

41 c together to obtain the next term in the series. 

42 

43 double precision n{10) , total 

44 dimension iresult(30) 

45 dimension j resul t{10 , 3) 

46 equivalence ( iresult (1 ) ,j result (1 , 1) ) 

47 

48 c Tell him which degree of Fibonacci series this is 

49 

50 print 

51 print, "Degree =", igrouping 
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52 






53 






54 


c 




55 


c 




56 


c 




57 


c 




58 






59 






60 






61 




10 


62 






63 






64 






65 


c 




66 


c 




67 






68 






69 






70 






71 




15 


72 






73 




20 


74 






75 


c 




76 


c 




77 


c 




78 


C 




79 


c 




30 


c 




31 






32 


- 




83 






84 






85 






86 




22 


87 






88 




25 


89 




30 


90 







WORKSHOP ONE 

print 

Initialize the assumed values which begin the 
series. All are but the last, which is 
1 - also put the assumed values into the 
output array 

do 10 i = 1, igrouping-1 

iresult(i) = 

n(i) = 

iresult( igrouping) = 1 

n(igrouping) = 1 

Compute remaining values of series, and put in 
the output array 

do 20 icycle = igrouping+1, icount 

total = 

do 15 i = 1, igrouping 

total = total + n(i) 

iresult{ icycle) = total 

n{mod ( icycle-1 , igrouping) } = total 

The output will be printed with assumed values 
preceding computed values. The computed values 
will be printed along with the assumed values 
in three columns. Hence, there will always be 
'irow' rows with three values, and the last ' 
row may have 1 2 or 3 values 

icol = mod { icount, 3) 
irow = icount / 3 

do 22 j=l,irow 

print, ( j result ( i, j) ,i=l,3) 

if (icol) 30,30,25 

print, ( j result ( irow+i, i) , i=l, icol) 

return 

end 
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The following dialogue shows the correct operation of the PL/I version 
of the fib program. The dialogue is slightly different for the 
FORTRAN and COBOL versions, but the concept is basically the same for 
all three programs. The programs shown above may have errors which 
prevent them from generating these results. Use probe to find the 
errors. Change the source to correct 'the errors, recompile the 
program and continue testing it until it prints the results shown 
below. 



! l s 


i ~> 


i i 


1 4 


1 5 ! 


1 6 


I 7 


1 8 


! 9 


1 10 


1 11 


1 12 


1 13 


1 14 


1 15 


1 16 


1 17 


1 18 


1 19 


1 20 


1 21 


1 22 


1 23 


1 24 


1 25 


I 26 


1 27 


1 28 


i 29 


1 30 


I 31 


1 32 


1 33 


1 34 


I 35 


1 36 


! 37 


1 38 



. pll fib -table 

PL/I 

r~2247 5.091 51.312 227 

! fib 

Enter Fdeg and/or count, followed by a ";" character. 
For example, 

Fdeg = 2, count=10; 
These are the default values. To stop, enter 

Fdeg = 1; 

Enter data, or just a ";" char: 1 Fdeg = 4, count=9; 



count= 9; 

Fdeg = 2: 

(assumed beginning of series) 

1 

(remainder of series) 

1 2 3 5 8 13 21 34 55 



Fdeg = 3: 

(assumed beginning of series) 

1 

(remainder of series) 

1 2 4 7 13 24 44 81 149 



Fdeg = 4: 

(assumed beginning of series) 

1 
(remainder of series) 

1 2 4 8 15 29 56 108 208 



New data, or just a " ; " char: I Fdeg=l; 
r 2248 0.249 0.228 19 
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A trace Workshop 



Use 'trace' to monitor the value of the arguments on return from 
the system program ' expand_pathname_' (trace -ag 1 -out 
expand_pathname_) . Do you know what that program is used for? 
Issue the trace~command to list the status of the expand_pathname 
trace entry (trace -status expand_pathname_) . Do you know what 
those counters mean? Now issue a print command and observe what 
happens. Issue the command 'print >ldd> include>its .incl .pll ' and 
see what happens. Now try the command ' ds baloney'. Finally, try 
the command ' pr Ofoo'. What happens? What do you think the 
fourth argument of expand pathname_ is used for?? 

Now print the status of the expand pathname^ (trace -status 
expand_pathname_) . Also, list the control template for trace 
(trace -tp) . Remove the trace entry for expand_pathname_ and 
reset the control template to its initial form (trace -remove 
expand_pathname_ -ag 0). 

Execute the following recursive program (see >udd>F19>sl>R2. pi] 
and >udd>F19>sl>R2) : 

R2: proc; 

del (sysin, sysprint) file; 

del (n, i) fixed bin; 

del R2$Seq entry (fixed bin); 

open file (sysprint) stream output env (interactive); 
put file (sysprint) skip list ("Enter value..."); 
gat list (n) ; 
call R2$Seq (n) ; 
.return; 

See: entry ( i) ; 

put file (sysprint) list (i); 
if i > 1 then do; 

call R2$Seq ( i-1); 

put file (sysprint) list (i); 



end; 



end; 



Execute the program with a value of 5. You should get 5 4 3 2 12 
3 4 5. Type the command to trace this program, printing the 
argument values at input to every second call (trace -in -ag 2 
R2$Seq) . Now run R2 again using the value 5 and observe what 
happens. List the trace status of R2$Seq and then turn on the 
governing facility (trace -st R2$Seq -govern on R2SSeq) . The 
governing facility is used to help trap runaway recursive 
procedures. Run R2 once again, using the value 5. List the 
status of R2$Seq(trace -st R2$Seq) . Note the maximum recursion 
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level. Now lets see if we can blow it out. Run R2 again, this 
time with an input of 12. What happened? Since our procedure is 
not really a runaway program, type the 'start' command to 
continue. Did you realize that we were at command level? 
Why? (Hint: the govern facility stops on depth levels which are a 
multiple of 10 to give you a chance to find out what's happening). 

4. Now, stop tracing R2$Seq, and reset the template. You may first 
want to issue the command 'trace -st * -tp' to see the current 
state of affairs. Next, copy the following three simple pll 
programs, which are found in the directory >udd>F19>sl: 

init: proc; 

del 1 S external static, 

2 sentinel fixed bin, 

2 array (5) float; 
del ioa_ entry options (variable); 
del addr builtin; 

sentinel = 0; 

call ioa_ ("sentinel located at "p", addr (sentinel)); 
end; 

load: proc; 

del sysprint file; 

del 1 S external static, 

2 sentinel fixed bin, 

2 array (5) float; 
del i fixed bin; 

open file (sysprint) stream output env (interactive); 
do i = 1 to 5; 

array (i) = 3* (i-2); 
end; 

put file (sysprint) skip (3) list (array); 
end; 
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print_stat: proc; 

del sysprint file; 

del 1 S external static, 
2 sentinel fixed bin, 
2 array (5) float; 



end; 



open file (sysprint) stream output env (interactive); 
put skip (2) list ("*sentinel location clobbered i !*") ; 
put Skip (1) data (S); 



Compile each of these programs. Now run init. It should tell you 
that the external static member variable 'sentinel' is located at 
some segment number I of f set. We want to use the watch facility of 
trace to find out whether any program is clobbering that location. 
Hence, issue the command to have trace watch that location -ffe**ce 
Swatch seg_no! of fset) . Next, let's monitor the 'load' program, 
and if anything goes wrong, let's cause the print_stat program to 
be called as the 'stop_proc' instead of the command processor. 
Issue the command to do this(trace -stop__proc print stat load). 
Mow run the load program and see what happens. So Tar so good! 
Now modify the load program so that it inadvertently changes the 
value of sentinel by changing the 'do' statement to "'do i = to 
5'. Recompile and run the load program. What happens? The watch 
facility should have stopped your load program since the value of 
its watch location changed, and it should have called the 
appropriate 'stop_proc'. Did it? The watch facility is very 
useful when trying to track down the one procedure in a group of 
procedures that is going a bit awry, or has modified some 
externally accessible error cell, etc. 
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On the Programming Environment: A Quiz 

1. Object segments are an essential part of the Multics programming 
environment.. Name the 8 sections into which an object segment is 
divided. Describe the contents of each section in general terras. 
Are all the sections always present in every object segment? If 
not, which are optional. 
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The system maintains information about the user ring programming 
environment in 2 important segments. Can you name these 2 
segments? Briefly describe what kinds of data the system keeps 
in each segment. What directory are the segments located in? 
How are these segments protected from accidental damage? 
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One of the most powerful features of the Multics programming 
environment is the Dynamic Linking mechanism. The programming 
environment uses this mechanism to find an object segment which 
is called by another program. 

Briefly name the important steps taken by the dynamic linker to 
find an object segment. 



At what point during the compilation or execution of the calling 
program does dynamic linking take place? 



How often does it take place? 



If one program calls an object segment and then a second program 
{a second object segment) calls that same target object segment, 
are the same steps followed in both cases to dynamically link to 
the called object segment? If not, how does dynamic linking 
differ during the second call? 
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4. A fatal process error occurs when the system decides fc hat the 
programming environment can no longer operate correctly. When 
this occurs, the system takes control of the user's terminal, 
prints a brief error message, and creates a new user process. 



pf. 

r- '? 



Under what circumstances might the system decide that the 
.ijprog ramming environment can no longer operate? 



What 2 programming errors are the most common causes of fatal 
process errors? 



Briefly describe a procedure for finding the cause of a fatal 
process error. 
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5. In chapter four 11 different classes of data (storage classes) 
were discussed which can be used in PL/I , FORTRAN and/or .COBOL 
programs. For each class of data, describe: 

o Where the data is stored. Give the logical name of a 
segment, table, or area; also give the pathname of the 
segment containing the data class. 

o The major characteristics of the storage class. (When the 
data is allocated, when freed, when initialized, can it be 
shared between programs, etc?) ,:, 

For example, one class of storage is: 

based storage, in an area: stored in a prog ram- supplied area, 
such as the system free area (segment system_f ree_n_ in the 
process dir) . Storage is known only to 1 program, is 
explicitly allocated and freed, is initialized by allocate 
or locate statements, and has a location maintained, by a 
pointer or offset qualifier. 
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5. (More .space for the answer) 



{5 5} 
V 



\ _, / Happiness is Multing the day away \ 
— \ / 

\ / 
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